netlify-deploy

netlify-deploy 技能概覽

netlify-deploy 是一個以部署為核心的技能，搭配 Netlify CLI 將 Web 專案發布到 Netlify。它最適合需要從本機 repo 到預覽或正式部署之間有一條可重複流程的使用者，尤其是專案可能需要先完成連結、初始化或驗證。

netlify-deploy 技能最有價值的地方，不只是「執行 deploy」，而是「判斷這個 repo 最適合走哪一種 Netlify 流程」。這包含偵測網站是否已經連結、判斷要做預覽還是正式部署，以及處理由 netlify.toml 驅動的建置設定。

這個技能適合做什麼

當你想要以下事情時，請使用 netlify-deploy 技能：

• 將本機 Web app、靜態網站或框架型應用部署到 Netlify
• 為新專案建立第一次部署
• 將既有 Git repo 或本機資料夾連結到現有的 Netlify site
• 在正式上線前先產出預覽部署

它和其他做法有什麼不同

netlify-deploy 的主要價值在於流程指引，而不只是命令清單。它以 Netlify CLI 為中心，會先檢查驗證狀態，並把常見阻礙納入考量，例如網站尚未連結、缺少 publish directory，或 build 設定不完整。

最適合的使用情境

這個技能最適合已經有實際專案目錄、而且想要一條可信部署路徑的使用者。若只是抽象地問「我要怎麼用 Netlify？」而沒有準備好針對特定 repo 動作，這個技能的幫助會比較有限。

如何使用 netlify-deploy 技能

先安裝並閱讀技能內容

使用 netlify-deploy install 時，先從技能條目本身開始，再閱讀會影響命令選擇的支援參考：

• SKILL.md
• references/cli-commands.md
• references/deployment-patterns.md
• references/netlify-toml.md

這裡沒有額外的 script 層，因此真正重要的決策支援都在參考文件裡。如果你需要在登入、連結、初始化、預覽部署與正式部署之間做選擇，請先看 deployment-patterns.md。

把模糊目標改寫成可用的提示

當使用者清楚說明 repo 狀態與部署目標時，這個技能的效果最好。好的 netlify-deploy usage 提示會包含：

• 已知的框架或建置工具
• 網站是否已經存在於 Netlify
• 目標是預覽還是正式部署
• 預期的建置輸出資料夾（如果已知）
• netlify.toml 是否已存在

範例：
「把這個 Vite app 部署到 Netlify。它還沒連結，我要正式部署，建置輸出是 dist。」

較弱的輸入：
「幫我部署我的網站。」

建議的工作流程

一個實用的 netlify-deploy guide 流程是：

1. 先用 npx netlify status 檢查驗證狀態。
2. 需要的話，再用 npx netlify login 完成登入。
3. 決定是要用 npx netlify link 連結既有網站，還是用 npx netlify init 建立新站。
4. 確認 netlify.toml 裡的建置輸出與設定。
5. 執行 npx netlify deploy 產生預覽部署，或執行 npx netlify deploy --prod 進行正式部署。

善用設定檔來減少猜測

部署前，先檢查是否存在 netlify.toml。最重要的欄位是 build.command、build.publish，以及任何依 context 設定的環境變數。如果 publish 路徑和實際建置輸出不一致，部署可能看似成功，卻會提供錯誤目錄，或在驗證時失敗。

netlify-deploy 技能 FAQ

netlify-deploy 只適合 Netlify CLI 使用者嗎？

是。這個技能是圍繞 npx netlify 與 CLI 流程設計的。如果你偏好只用儀表板部署，這可能不是最適合的選擇。

使用前一定要先把專案連結好嗎？

不用。netlify-deploy skill 同時涵蓋首次設定與既有網站。如果 repo 還沒連結，流程應該先改走 link 或 init，再進行部署。

這比一般的 deploy 提示更好嗎？

通常是，因為 netlify-deploy 內建了 Netlify 的真實順序：先驗證、再連結或初始化、接著確認設定，最後部署。這能降低漏掉前置步驟而導致部署失敗的機率。

什麼情況下不該使用它？

如果專案不是 Web app、你無法執行 CLI 指令，或你需要的是更廣泛的主機方案比較，而不是 Netlify 專屬流程，就不適合使用 netlify-deploy。

如何改進 netlify-deploy 技能

提供會改變部署路徑的 repo 實際資訊

最大的品質提升，來自把技能無法安全推斷的資訊直接講清楚：

• framework：Next.js、Astro、Vite、SvelteKit 等
• build command：npm run build、pnpm build 或自訂指令
• publish directory：dist、build、.next 或其他
• site 狀態：新專案、已連結，或已經部署過
• 目標：預覽或正式

這些細節能幫助 netlify-deploy 技能直接選對 CLI 路徑，少走試錯流程。

及早指出設定不一致的地方

常見失敗模式，是以為 Netlify 會自動把所有東西都判斷正確。如果你的 app 使用非標準輸出目錄、monorepo 版面，或自訂 base path，請一開始就說明，並把技能導向 netlify.toml。這對 monorepo 或框架特定建置的 netlify-deploy for Deployment 尤其重要。

要求第一次部署的完整形狀，不要只要一條命令

更好的結果通常來自要求包含整個步驟順序的輸出，而不只是單一指令。例如：
「請列出完整步驟，包含驗證、連結這個 repo、確認 netlify.toml，以及部署到 production。」

這樣能促使技能先說明部署命令執行前真正重要的決策點。

根據第一次部署結果再迭代

如果第一次部署失敗，請回傳具體錯誤與目前的檔案結構，不要從頭重問。最有用的後續資訊包括：

• npx netlify 的錯誤訊息
• netlify.toml 的內容
• 你的 framework 實際產生的建置輸出資料夾
• 在失敗前，網站是否已經完成連結

這樣下一步的 netlify-deploy usage 會更精準，也能避免重複已經成功過的驗證或連結步驟。