netlify-config

netlify-config 技能概覽

netlify-config 是用來做什麼的

netlify-config 技能是撰寫與調整 netlify.toml 的實用參考。當你需要設定 builds、redirects、rewrites、headers、deploy contexts、environment variables、functions 或 edge functions，而且不想靠猜 Netlify 語法時，就該使用 netlify-config 技能。

誰適合使用它

這個技能最適合已經知道自己要讓 Netlify 做什麼、但需要可靠方式把設定正確表達出來的使用者。netlify-config 指南特別適合處理那些很容易細節出錯的部署變更，例如 redirect 順序、catch-all routing，或依 context 而不同的設定。

它為什麼有用

這個技能聚焦在會真正影響部署行為的設定細節：檔案放置位置、TOML 結構、規則比對，以及 Netlify 專有的 options，例如條件與強制規則。若你在判斷該用一般提示詞，還是用 netlify-config 技能，當正確性比腦力激盪更重要時，這個技能會更適合。

如何使用 netlify-config 技能

安裝並載入這個技能

在你的 skills 工作流程中使用 netlify-config 的安裝流程，接著先打開 skills/netlify-config/SKILL.md 作為起點。這個 repository 目前把這個技能做成單一檔案參考，所以不需要再去找其他 helper scripts 或搭配資源。

把你的目標轉成可用的提示

netlify-config 最好的使用方式，是先給出明確的部署目標，而不是模糊需求。好的輸入會寫清楚網站類型、你正在編輯的檔案，以及你要的結果。舉例來說：Update netlify.toml so /docs/* rewrites to /docs/index.html in production, but keep /api/* proxying to the backend in all deploy contexts.

先讀對的部分

先看 build settings 與 redirects 的範例，再去檢查與你變更內容相符的章節：headers、deploy contexts、functions 或 edge functions。實務上，要把 netlify-config 用在 Deployment 上，最快的方法是先把你想要的 routing 行為對照到最接近的範例，再依此調整語法，而不是從零發明。

提升輸出品質的技巧

提供技能目前的檔案路徑、framework 的輸出目錄，以及任何已存在且可能衝突的規則。也要說明你需要的是 rewrite、redirect 還是 proxy，因為這些選擇會影響正確的 status 值，以及是否需要 force。如果你在 monorepo 裡工作，請明確指出 base directory，這樣設定才會落在正確位置。

netlify-config 技能 FAQ

netlify-config 只適用於 netlify.toml 嗎？

是的，netlify-config 技能的核心就是 netlify.toml 以及它所控制的部署行為。如果你的問題牽涉更廣泛的 Netlify hosting 策略，當核心任務是設定語法或規則設計時，這個技能仍然有幫助。

什麼時候一般提示詞就夠了？

像「Netlify redirects 怎麼運作？」這類粗略概念，一般提示詞就夠了。當你需要可直接部署的答案時，netlify-config 技能會更適合，尤其是 routing precedence、rewrites，或依 context 而不同的設定，這些地方小小的語法錯誤就可能造成 build 壞掉。

它適合初學者嗎？

可以，只要你能用白話描述自己的部署目標。真正的門檻不是技能難度，而是輸入不完整。初學者如果提供目前的 build command、publish folder，以及想要調整的 path patterns，通常會得到更好的結果。

什麼情況下不該用它？

如果你還在平台之間猶豫，或還不知道這個變更應該放在 redirects、headers，還是 build settings，就先不要用 netlify-config。這是一個設定技能，不是通用的 Netlify 說明工具，也不是網站架構顧問。

如何改善 netlify-config 技能

提供精確的 routing 問題

最強的 netlify-config 技能輸出，通常來自精準的 path 範例。不要只說「修 redirects」，而是提供舊路徑、目標路徑、想要的 status code，以及任何例外情況。這樣技能才能在 301、302、200 和 404 之間做出不含糊的選擇。

加入部署情境與限制

對 netlify-config for Deployment 來說，情境很重要：production-only 行為、preview deploy 的差異，以及 environment-specific variables，都會改變正確答案。請說明規則是要全域套用，還是只在某個 deploy context 下生效，並提到任何既有的 CMS、SPA 或 API 限制。

要求直接給最終檔案，不只要建議

有用的 netlify-config 指南型需求，應該要求直接提供你可以貼上的精確 netlify.toml 片段，外加一段簡短說明，告訴你它應該放在檔案哪裡。這樣可以減少來回溝通，也更容易在部署前發現順序錯誤。

從第一次部署測試開始迭代

第一版設定寫好之後，請測試實際的 path 行為，並依 Netlify 真正提供的結果調整。常見失敗模式包括 rule shadowing、漏掉 force = true，以及把 redirects 和 rewrites 混淆；下一輪提示詞應該描述你觀察到的行為，而不只是原本想要的結果。