netlify-deploy

netlify-deploy 技能概览

netlify-deploy 是一个面向部署的技能，用于借助 Netlify CLI 将 Web 项目发布到 Netlify。它最适合需要从本地仓库稳定走到预览或生产部署的用户，尤其是项目可能还需要先完成关联、初始化或认证时。

当任务不只是“执行 deploy”，而是“先判断这个仓库该走哪条 Netlify 流程”时，netlify-deploy 最有用。它会帮你识别站点是否已经关联，判断应该做 preview 还是 production，以及处理由 netlify.toml 驱动的构建设置。

这个技能适合做什么

当你想要以下操作时，使用 netlify-deploy 技能：

• 将本地 Web 应用、静态站点或框架应用部署到 Netlify
• 为新项目创建第一次部署
• 将已有 Git 仓库或本地文件夹关联到现有 Netlify 站点
• 在正式发布前先生成预览部署

它有什么不同

netlify-deploy 的核心价值不是命令清单，而是流程指导。它以 Netlify CLI 为中心，先检查认证状态，并会考虑常见阻碍，比如站点未关联、发布目录缺失，或构建配置不完整。

什么时候最适合用

这个技能适合已经有真实项目目录、并希望拥有一条可靠部署路径的用户。对于那种抽象的“我该怎么用 Netlify？”类问题，它就没那么适用，除非用户已经准备好对某个具体仓库动手。

如何使用 netlify-deploy 技能

先安装并阅读技能内容

执行 netlify-deploy install 时，先从技能条目本身开始，再阅读决定命令选择的支持性参考：

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

这里没有脚本层，所以真正重要的决策支持都在这些参考文件里。如果你需要在登录、link、init、preview deploy 和 production deploy 之间做选择，先读 deployment-patterns.md。

把模糊目标改写成可执行提示

这个技能在用户把仓库状态和部署目标说清楚时效果最好。一个好的 netlify-deploy usage 提示应包含：

• 已知的话：框架或构建工具
• 站点是否已经存在于 Netlify
• 目标是 preview 还是 production
• 已知的话：预期的构建输出目录
• netlify.toml 是否已经存在

示例：
“把这个 Vite 应用部署到 Netlify。它还没关联，我要 production deploy，构建输出是 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，以及任何按环境区分的环境变量设置。如果发布路径和实际构建输出不一致，部署可能表面成功，却会服务到错误目录，或者在校验时失败。

netlify-deploy 技能 FAQ

netlify-deploy 只适合 Netlify CLI 用户吗？

是的。这个技能是围绕 npx netlify 和 CLI 工作流设计的。如果你更偏好只用控制台面板完成部署，那它大概率不是最佳选择。

使用它之前必须已经关联项目吗？

不需要。netlify-deploy skill 同时覆盖首次配置和已有站点。如果仓库还没关联，工作流应该先转向 link 或 init，再进行部署。

它比通用部署提示更好吗？

通常是更好的，因为 netlify-deploy 内置了真实的 Netlify 顺序：先认证，再 link 或 init，接着确认配置，最后部署。这样可以降低漏掉前置步骤、导致部署被卡住的概率。

什么时候不该用它？

如果项目不是 Web 应用、你无法运行 CLI 命令，或者你需要的是更广泛的托管方案对比，而不是 Netlify 专用流程，就不要用 netlify-deploy。

如何改进 netlify-deploy 技能

提供会改变部署路径的仓库信息

最能提升效果的是把技能无法安全推断的信息直接说清楚：

• 框架：Next.js、Astro、Vite、SvelteKit 等
• 构建命令：npm run build、pnpm build 或自定义命令
• 发布目录：dist、build、.next 或其他
• 站点状态：新建、已关联，或已经部署过
• 目标：preview 还是 production

这些信息能帮助 netlify-deploy 技能在不反复试错的情况下选对 CLI 路径。

尽早暴露配置不匹配

一个常见失败模式，是默认 Netlify 能把一切都自动识别正确。如果你的应用使用非标准输出目录、monorepo 结构，或者自定义 base path，请提前说明，并把技能引导到 netlify.toml。这对 monorepo 场景或框架特定构建下的 netlify-deploy for Deployment 尤其重要。

先要部署形态，再要单行命令

更好的结果来自于要求输出完整步骤，而不是只给一行命令。比如：
“请展示确切步骤：如何认证、关联这个仓库、验证 netlify.toml，然后部署到 production。”

这样能促使技能先解释部署命令之前真正重要的决策点。

根据首次部署结果继续迭代

如果第一次部署失败，不要从头再问一遍，而是把具体失败信息和当前文件结构反馈回来。最有用的后续输入包括：

• npx netlify 输出的错误信息
• netlify.toml 的内容
• 你的框架实际生成的构建输出目录
• 站点在失败前是否已经完成关联

这样下一步的 netlify-deploy usage 会更精准，也能避免重复执行那些已经成功过的认证或关联步骤。