netlify-config

netlify-config 技能概览

netlify-config 是用来做什么的

netlify-config 技能是编写和调整 netlify.toml 的实用参考。需要配置 build、redirect、rewrite、header、deploy context、环境变量、functions 或 edge functions，又不想靠猜 Netlify 语法时，就该用 netlify-config 技能。

谁适合用它

它最适合已经明确知道想让 Netlify 做什么、但需要一种可靠方式把配置准确表达出来的构建者。netlify-config 指南尤其适合那些很容易在细节上出错的部署改动，比如 redirect 顺序、catch-all 路由，或者按 context 区分的设置。

它为什么有用

这个技能聚焦的是会直接影响真实部署行为的配置细节：文件放置位置、TOML 结构、规则匹配，以及 Netlify 特有的选项，比如 conditions 和 force 规则。如果你在犹豫是直接提问还是用 netlify-config 技能，当正确性比发散式构思更重要时，技能版通常更合适。

如何使用 netlify-config 技能

安装并加载这个技能

先按你的 skills 工作流完成 netlify-config 的安装流程，然后打开 skills/netlify-config/SKILL.md 作为起点。这个仓库目前把该技能做成了单文件参考，所以没有额外的辅助脚本或配套资源需要继续找。

把你的目标变成可用的提示词

最好的 netlify-config 用法，始于一个具体的部署目标，而不是笼统请求。高质量输入会写清站点类型、你正在编辑的文件，以及你需要的结果。例如：“更新 netlify.toml，让 /docs/* 在生产环境重写到 /docs/index.html，但在所有 deploy context 下都继续把 /api/* 代理到后端。”

先读对的部分

先看 build settings 和 redirects 的示例，再根据你的改动去找对应章节：headers、deploy contexts、functions 或 edge functions。实际使用 netlify-config 处理 Deployment 时，最快的方法是先把你想要的路由行为对应到最接近的示例，再在此基础上调整语法，而不是从头自己造。

提升输出质量的小技巧

把当前文件路径、framework 的输出目录，以及已经存在的冲突规则都告诉技能。说明你需要的是 rewrite、redirect 还是 proxy，因为这些选择会改变正确的 status 值，以及是否需要 force。如果你在 monorepo 里工作，务必明确写出 base directory，这样配置才会落到正确位置。

netlify-config 技能 FAQ

netlify-config 只用于 netlify.toml 吗？

是的，netlify-config 技能的核心就是 netlify.toml 以及它所控制的部署行为。如果你的问题更偏向整体 Netlify 托管策略，只要核心任务是配置语法或规则设计，这个技能仍然有帮助。

什么时候普通提示词就够了？

如果只是问一些粗略概念，比如“Netlify redirects 是怎么工作的？”，普通提示词就够了。netlify-config 技能更适合你需要一个可直接用于部署的答案，尤其是在路由优先级、rewrite，或者按 context 区分设置这些地方，细小语法错误都可能导致构建或上线出问题。

它对新手友好吗？

可以，只要你能用自然语言说清部署目标。主要障碍不是技能本身难，而是输入不完整。新手如果提供当前 build command、publish folder，以及想改动的路径模式，通常会得到更好的结果。

什么时候不该用它？

如果你还在平台之间犹豫，或者还不确定这项改动该放进 redirects、headers 还是 build settings，就不要用 netlify-config。它是配置技能，不是通用的 Netlify 讲解器，也不是站点架构顾问。

如何改进 netlify-config 技能

提供精确的路由问题

netlify-config 技能最强的输出，通常来自精确的路径示例。不要只说“修复 redirects”，而要给出旧路径、目标路径、期望的状态码，以及任何例外情况。这样技能才能在 301、302、200 和 404 之间不含糊地做选择。

补充部署上下文和限制

对于 netlify-config for Deployment 来说，上下文非常关键：只在生产环境生效、preview deploy 的差异、以及环境变量的不同，都会改变正确答案。要说明这条规则是全局生效还是只在某个 deploy context 下生效，并提到任何现有的 CMS、SPA 或 API 约束。

要最终文件，不只是建议

一个有用的 netlify-config 指南请求，应该直接要求给出可以粘贴的完整 netlify.toml 片段，并附上一句简短说明，告诉你它应该放在文件的哪里。这样能减少来回沟通，也更容易在部署前发现顺序错误。

从第一次部署测试开始迭代

写好第一版配置后，先测试真实路径行为，再根据 Netlify 实际返回的结果继续调整。常见失败模式包括规则遮蔽、漏写 force = true，以及把 redirects 和 rewrites 混淆；下一轮提问应该描述你观察到的行为，而不只是你原本想要的效果。