前言¶
前端項目寫完之後，往往還要經歷一遍熟悉又瑣碎的上線流程：登錄託管平臺、關聯站點、確認構建命令和發佈目錄、先打預覽再推生產。命令本身不復雜，但步驟多、容易漏，尤其在用 AI 編程助手幫你改代碼時，助手如果對 Netlify CLI 的約定不熟，就容易卡在鑑權、站點未關聯，或把預覽部署和正式發佈搞混。
netlify-deploy 正是爲這類場景準備的 Agent Skill。它把「檢查登錄 → 關聯或新建站點 → 安裝依賴 → 預覽/生產部署」固化成可複用的流程說明，讓支持 Agent Skills 標準的工具（如 Cursor、Codex、Claude Code）在你提到部署、託管、發佈到 Netlify 時，按同一套步驟執行，而不是臨時拼命令。
這是什麼¶
netlify-deploy 是 OpenAI 在 openai/skills 倉庫 skills/.curated/ 目錄下收錄的一份 curated Skill，官方路徑爲：
https://github.com/openai/skills/tree/main/skills/.curated/netlify-deploy
它的定位很明確：通過 Netlify CLI（文檔與示例統一使用 npx netlify，不必先全局安裝）完成 Web 項目的部署、託管與發佈，覆蓋預覽部署和生產部署。觸發場景包括用戶說「部署到 Netlify」「發佈站點」「關聯現有站點」等。
需要說明的是：該倉庫 README 已提示整體 deprecated，後續 Codex 相關示例更推薦參考 openai/plugins；但截至本文寫作時，netlify-deploy 的 SKILL.md 與配套 references/ 仍可從上述 curated 路徑獲取。Skill 基於通用的 SKILL.md 格式（可參見 Agent Skills 開放標準），因此同一份技能包可以放到不同 AI 編程工具對應的 skills 目錄中使用。
核心功能與亮點¶
根據官方 SKILL.md，這個 Skill 主要自動化以下幾件事：
-
校驗 Netlify CLI 登錄狀態
先跑npx netlify status。未登錄則引導執行npx netlify login（瀏覽器 OAuth）；也可以改用環境變量NETLIFY_AUTH_TOKEN（在 Netlify 用戶設置裏生成 Personal Access Token）。 -
識別項目是否已關聯站點
從status輸出判斷當前目錄是否已 link 到某個 Netlify site。已關聯則直接進入部署；未關聯則嘗試按 Git remote 鏈接，或走新建流程。 -
關聯已有站點或創建新站點
- 有 Git remote 時：npx netlify link --git-remote-url <REMOTE_URL>
- 鏈接失敗或不存在站點：npx netlify init（選團隊、站點名、構建配置，必要時生成netlify.toml） -
部署前檢查依賴
對 npm 項目執行npm install；若檢測到 yarn / pnpm 等，則使用對應安裝命令。 -
區分預覽與生產
- 已有站點、默認測試：npx netlify deploy（Draft/Preview，得到獨立預覽 URL）
- 新站點或明確要上線：npx netlify deploy --prod
CLI 會讀取netlify.toml，或交互詢問 build command / publish directory；Skill 也會盡量根據package.json推斷框架默認值。 -
結果回報與排錯指引
部署結束後應向用戶回報 Deploy URL、生產站點 URL（若走了--prod）、控制檯日誌入口，並可提示netlify open。常見錯誤（未登錄、未關聯站點、構建失敗、發佈目錄不存在）在 Skill 裏都有對應處理建議。
Skill 目錄裏還附帶按需加載的參考文檔：references/cli-commands.md、references/deployment-patterns.md、references/netlify-toml.md，用來補充命令速查、場景決策樹和配置說明，避免把所有細節塞進主 SKILL.md。
安裝與啓用¶
獲取 Skill 文件¶
從官方目錄獲取 netlify-deploy 文件夾（至少包含 SKILL.md，建議一併保留 references/）：
# 克隆倉庫後拷貝 curated 技能目錄（任選一種獲取方式）
git clone https://github.com/openai/skills.git
cp -r openai/skills/skills/.curated/netlify-deploy <你的-skills-目錄>/netlify-deploy
在 Codex 中，也可按 openai/skills 文檔使用內置安裝器安裝 curated 技能（安裝後如未識別，需重啓 Codex）：
$skill-installer netlify-deploy
放到各工具的 skills 目錄¶
Agent Skills 是「一個目錄 + 一份 SKILL.md」。不同工具掃描路徑不同，可按官方文檔放置（項目級或用戶級均可）：
| 工具 | 常見項目級路徑 | 常見用戶級路徑 |
|---|---|---|
| Cursor | .cursor/skills/netlify-deploy/ 或 .agents/skills/netlify-deploy/ |
~/.cursor/skills/、~/.agents/skills/ |
| Claude Code | .claude/skills/netlify-deploy/ |
~/.claude/skills/netlify-deploy/ |
| Codex | .agents/skills/netlify-deploy/ |
~/.agents/skills/ |
目錄結構示意：
netlify-deploy/
├── SKILL.md
└── references/
├── cli-commands.md
├── deployment-patterns.md
└── netlify-toml.md
Cursor 文檔還說明：爲兼容性會額外加載 .claude/skills/、.codex/skills/ 等路徑。跨工具協作時，優先使用 .agents/skills/ 往往更省事。
運行時前置條件¶
Skill 本身不替代 Netlify 賬號與網絡權限，使用前需滿足：
- 本機可執行 Node.js 環境，以便
npx netlify ...（Netlify 官方 CLI 文檔要求 Node.js 18.14.0 或更高；Skill 側通過 npx 調用，不強制全局npm install -g netlify-cli） - 已登錄 Netlify，或已設置
NETLIFY_AUTH_TOKEN - 當前目錄是有效的 Web 項目
- 若沙箱攔截了出站網絡，Skill 提示需用更高權限重試（文檔中的
sandbox_permissions=require_escalated）；部署可能需要數分鐘，注意超時設置
典型用法示例¶
下面流程來自官方 SKILL.md 的完整示例，可在本地或讓 Agent 按步驟執行。
1. 鑑權¶
npx netlify status
# 若未登錄：
npx netlify login
# 無瀏覽器環境時，可用 Token：
export NETLIFY_AUTH_TOKEN=your_token_here
Token 可在 https://app.netlify.com/user/applications#personal-access-tokens 生成。這與 Netlify 官方 CLI 文檔中的鑑權方式一致。
2. 關聯或初始化站點¶
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo
# 若站點尚不存在：
npx netlify init
3. 安裝依賴並部署¶
npm install
# 先預覽（Draft Deploy）
npx netlify deploy
# 確認無誤後再上生產
npx netlify deploy --prod
4. 構建配置（netlify.toml）¶
若倉庫根目錄已有 netlify.toml，CLI 會自動使用。沒有時，CLI 會詢問構建命令與發佈目錄。Skill 給出的常見默認值示例包括：
- Next.js：
npm run build，發佈目錄.next - React（Vite）：
npm run build，發佈目錄dist - 純靜態 HTML：無需構建命令，發佈當前目錄
實際項目仍以本地構建產物目錄爲準。例如 Vite 也可顯式指定目錄：
npx netlify deploy --dir=dist --prod
部署模式選擇上，Skill 的 decision tree 建議：新站點或首次上線傾向 --prod；已有站點改代碼時先 deploy 預覽，再 --prod。
5. 對 Agent 可以說的話¶
啓用 Skill 後，不必背命令，直接描述意圖即可，例如：
- 「把當前 Vite 項目部署到 Netlify，先出預覽鏈接」
- 「用 Git remote 關聯已有 Netlify 站點並做生產發佈」
- 「這個倉庫還沒建過站點，幫我
netlify init再--prod」
Agent 應按 Skill 先查 status、處理登錄與 link，再部署，而不是跳過鑑權直接 deploy。
適用場景與注意事項¶
比較適合：
- 個人或小團隊的靜態站、Vite/React、簡單前端項目，希望「改完就能預覽 URL」
- 用 AI 助手寫頁面時，把「上線」也交給同一會話閉環處理
- 需要統一團隊部署話術與步驟（預覽優先、密鑰不進 Git、依賴先裝好）
使用時注意：
- 先預覽再生產：Skill 明確建議多數已有站點先跑無
--prod的deploy，確認預覽 URL 後再正式發佈。 - 密鑰不要提交倉庫：環境變量應放在 Netlify 控制檯（Site Settings → Environment Variables）或用
npx netlify env:set，構建裏通過process.env讀取。 - 構建失敗先本地復現：發佈目錄不存在、exit code 1 等，優先本地
npm run build覈對輸出目錄與netlify.toml。 - 網絡與沙箱：在受限沙箱裏部署失敗時，按 Skill 提示申請放寬網絡權限後再試。
- 倉庫狀態：引用 openai/skills 時留意其 README 的 deprecated 說明；若你所在工具生態已遷移到 plugins 分發，以當前工具文檔的安裝方式爲準，Skill 內容仍以
SKILL.md爲準。 - 框架特例：不同框架在 Netlify 上的最佳構建配置可能隨平臺演進變化；Skill 中的默認值是引導建議，複雜項目（尤其 Next.js 等）應再對照 Netlify 框架文檔 與 CLI 入門 覈對。
部署完成後，可用 npx netlify open 打開控制檯，若使用了 Netlify Functions，可用 npx netlify logs 查看函數日誌；本地聯調 Functions 可用 npx netlify dev。
小結¶
netlify-deploy 把 Netlify CLI 上線鏈路寫成 Agent 可執行的標準流程：登錄校驗、站點關聯、依賴安裝、預覽與生產分離，並附帶命令與場景參考。對經常把前端 demo 推到 Netlify 的開發者來說，它補上的是「寫完即上線」閉環裏最容易被助手漏掉的那幾步。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/netlify-deploy
Netlify CLI 文檔：https://docs.netlify.com/cli/get-started/
netlify.toml 參考：https://docs.netlify.com/configure-builds/file-based-configuration/
