netlify-deploy

Netlify 部署

现代 CLI

netlify deploy              # manual draft deploy (no CI)
netlify deploy --prod       # deploy straight to production
netlify create              # new project from a natural-language prompt
netlify deploy --allow-anonymous   # temp project, claim within 1 hour
npm update -g netlify-cli   # skew protection needs 23.11.0+

部署是一个带版本的原子快照：Netlify 只上传有变化的文件，并且仅在所有文件就位后切换线上站点，因此站点绝不会处于不一致状态。部署可以是预览版本，也可以是通过主域名提供服务的生产版本。

**持续部署与手动部署：**通过 Git 和 Netlify CLI 部署支持持续部署——推送会自动触发构建。拖放和 API 会创建一次性手动部署。手动部署（netlify deploy）不会运行构建命令；登录状态下的拖放是唯一例外（会自动检测框架）。

**⚠ 链接或创建站点时，请将 .netlify 添加到 .gitignore。**每种链接方式都会写入 .netlify/state.json，该文件不得提交。

创建部署的方式

• Git CD — 连接代码仓库；Netlify 会在每次推送时构建并部署（OAuth2 或 Netlify GitHub App）。这是默认方式。生产部署来自推送到生产分支的提交——通常是代码仓库的默认分支（例如 main），可在 Branches and deploy contexts 中更改。
• CLI — netlify create、netlify deploy、netlify deploy --prod。
• 拖放 — https://app.netlify.com/drop。已登录：如有需要会进行构建。未登录：原样发布文件。
• API — 通过文件摘要或 ZIP 创建部署（一次性手动部署）。
• Deploy to Netlify 按钮 — 从公开模板代码仓库一键部署。
• 构建钩子 — 用于触发构建的唯一 URL。（通过构建钩子触发的部署会被视为可信，并绕过部署请求策略。）
• AI Agent — 从控制面板使用 Agent Runners（Claude Code、OpenAI Codex、Google Antigravity）；每次更改文件的运行都会自动生成 Deploy Preview，地址为 agent-<runID>--<site>.netlify.app。提示词旁显示的内嵌预览，与此 URL 上的 Deploy Preview 相同。
• Zapier / n8n — 自动化集成。

不确定该选哪种方式？Deploy Navigator 会提供个性化建议：https://docs.netlify.com/start/choose-your-path#deploy-navigator（也嵌入在创建部署页面中，标题为“Not sure where to start?”）。

netlify.toml 部署上下文

位于代码仓库根目录。文件配置会覆盖 UI 设置。五种预定义上下文：production、deploy-preview、branch-deploy、preview-server、dev。分支名称也可用作自定义上下文；更具体的上下文会覆盖一般上下文。

[context.production]
  command = "make production"
  [context.production.environment]
    ACCESS_TOKEN = "super secret"
  [[context.production.plugins]]        # plugins REQUIRE double brackets
    package = "@netlify/plugin-sitemap"

[context.deploy-preview.environment]
  ACCESS_TOKEN = "not so secret"

[context.branch-deploy]                 # all branch deploys
  command = "make staging"

[context.staging]                       # one branch; overrides branch-deploy
  command = "npm run build:staging-special"

[context.dev.environment]
  NODE_ENV = "development"

[context."features/branch"]             # quote slashed branch names
  command = "gulp"

⚠ 在 netlify.toml 中设置的环境变量无法用于部署环境——请通过 UI、CLI 或 API 设置。netlify.toml 会提交到代码仓库，因此请勿在其中存放敏感值；请改用通过 UI、CLI 或 API 设置的上下文专属环境变量。

完整的上下文优先级规则请参阅 references/netlify-toml.md，上下文策略请参阅 references/deployment-patterns.md。

部署预览和分支部署

• 部署预览会为 PR/MR（GitHub、GitLab、Bitbucket、Azure DevOps、Cursor Origin）和 Agent 运行自动构建。基础分支必须是生产分支或已启用分支部署的分支。URL：deploy-preview-<num>--<site>.netlify.app。首次部署待处理期间，URL 会返回 Not Found。
• 分支部署需要进行设置：Project configuration > Developer settings > Continuous deployment > Branches and deploy contexts > Configure。启用指定分支（支持前缀通配符 features/*），或启用 All new branches。URL：<branch>--<site>.netlify.app。只要分支存在，分支部署就会持续保留。构建设置/环境变量：所有分支使用 [context.branch-deploy]，单个分支使用 [context.<branch>]。
• 已启用分支部署的分支存在未关闭的 PR 时，会同时生成部署预览和分支部署。
• **入口路径：**在 PR/MR 描述中填写 @netlify /some/path，然后推送一个新提交以重新生成。PR 中设置后，就无法在 Netlify Drawer 中更改。
• 跳过部署：使用 [skip ci] 或 [skip netlify]——在 PR/MR 标题中使用可跳过部署预览；在提交消息的任意位置使用可跳过分支/生产部署。下一个未标记的提交会部署所有已跳过的更改。

锁定、跳过和手动生产部署

• 锁定（禁用自动发布）：Deploys 列表 > Lock to stop auto publishing。新部署仍会构建，但不会发布。解锁即可恢复。
• **⚠ 在 Git-CICD 站点上手动运行 netlify deploy --prod：**下一次推送到生产分支时，会静默替换你手动发布的部署。请提醒用户；如果必须让已发布的部署继续上线，请锁定该部署。

管理部署

• **查找：**Deploys 选项卡（Developer 或 Team Owner）；按部署 ID 或分支名称搜索；按时间范围、部署上下文和状态筛选。
• **取消：**在进行中部署的详情页，选择 Cancel deploy > Yes, cancel deploy。
• **重试：**从分支 HEAD 构建（可选择清除缓存）——如果 HEAD 已超出原部署的 SHA，仍会从 HEAD 构建。
• **下载：**在成功部署的详情页中，可通过 Deploy file browser 下载单个文件，或通过页眉中的 Download > Download ready 将所有文件下载为 ZIP。
• **删除：**仅限 Developer 或 Team Owner。无法删除最近一次发布到站点主 URL 的部署，也无法删除仍在进行中的部署。删除操作不可撤销，也不会降低团队成本或保留构建分钟数。

Deploy to Netlify 按钮

模板代码必须位于 GitHub.com 或 GitLab.com 上的公开仓库中。

Markdown：

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify/netlify-statuskit)

URL 变体（基础链接 https://app.netlify.com/start/deploy）：

# require/pre-fill env vars (hash, client-side only; values may be null)
...?repository=<repo>#SECRET_TOKEN=specialuniquevalue&CUSTOM_LOGO=

# monorepo base dir (whole repo cloned, builds from blog/)
...?repository=<repo>&base=blog

# clone only a subdirectory
...?repository=<repo>&create_from_path=examples/hello

# deploy a specific branch (sets it as production branch)
...?repository=<repo>&branch=beta-feature

# install required SDK extensions before first deploy
...?repository=<repo>&fullConfiguration=true

基于文件的模板配置，位于仓库根目录 netlify.toml 中的 [template]：

[template]
  incoming-hooks = ["Contentful"]
  required-extensions = ["supabase"]

[template.environment]
  SECRET_TOKEN = "change me for your secret token"
  CUSTOM_LOGO = "set the url to your custom logo here"

你不能在 [template] 中设置环境变量值或基础目录——请使用 URL 参数。[template.environment] 中的占位字符串仅用作界面标签。

**⚠ 模板配置（传入的钩子、模板环境变量）只会从仓库根目录读取。**当按钮通过 base 指向子目录时，基础目录中的 netlify.toml 会优先用于构建，但其中的模板配置会被忽略。请明确说明这一限制，不要只让读者自行推断。

密钥扫描失败

**⚠ 密钥扫描导致部署失败，意味着有一个看起来像密钥的值进入了构建输出。**如果它是真正的密钥，这就是泄露——停止将其发布到客户端/已发布的输出中，并轮换该密钥。绝不要为了掩盖真实泄露而设置 SECRETS_SCAN_ENABLED=false。对于确实不是密钥的值，请通过 SECRETS_SCAN_OMIT_KEYS / SECRETS_SCAN_OMIT_PATHS 精确限定排除范围。

修复部署失败问题——不回滚

部署失败不会发布——上一次部署仍在线，因此无需恢复。如果有人要求回滚或恢复之前的部署，请纠正这一前提：部署失败后没有任何变化；对于有问题的已发布部署，应向前修复——还原该提交，并让 CI 重新部署。不要调用 restoreSiteDeploy 或 publishDeploy，也不要把在控制面板中回滚作为解决方案。

Netlify 会在部署日志上方显示 Why did it fail? AI 诊断——此诊断及其建议的解决方案不会消耗额度。选择 Fix with agent 会启动 Agent 运行，这会消耗团队余额中的额度。请参阅 https://docs.netlify.com/resources/troubleshooting/fix-a-failed-deploy/。

部署权限（私有仓库）

Netlify 只会构建由已识别作者（所有者、开发者、Git 贡献者；Marketplace 机器人也算）推送到私有仓库的更改。未识别作者合并的更改会显示 Pending approval；团队所有者必须先将其关联到团队账号，构建才会开始。构建钩子部署不受此限制。

限制与注意事项

• 每个目录最多 54,000 个文件。 发布目录中的任何目录超出此数量都会导致部署失败。每次部署的文件总数没有限制。
• 版本偏移保护： 所有套餐均支持；仅限生产环境上下文——分支部署、Deploy Preview 和永久链接会绕过此保护，并提供最新部署。需要 Netlify CLI 23.11.0+。Astro 5.15.0+ 通过 Netlify Adapter 默认启用此功能；Next.js 则需选择启用。在生产部署（或所有部署）上启用密码保护会关闭版本偏移保护——只有仅保护非生产部署时，此功能才有效。对于硬导航（Sec-Fetch-Mode: navigate，或存在 Sec-Fetch-Site 且其值不是 same-origin），Netlify 会丢弃版本偏移保护信号。框架维护者可通过 netlify/v1/skew-protection.json 添加支持。
• ⚠ 搜索索引——最新的分支部署可以被索引： Netlify 会为 Deploy Preview 和较旧的分支部署添加 X-Robots-Tag: noindex，但不会为每个分支最新的分支部署添加此标头，因此搜索引擎可能会抓取 staging--<site>.netlify.app。无论如何，标头都不是保证。若要让预览/分支部署不出现在搜索结果中，请通过项目可见性将项目设为私有（仅限基于 Credit 的套餐），或为非生产部署启用密码保护（此范围设置也能保持版本偏移保护正常工作）。
• 预览 URL 可见性： 任何持有链接的人都可以访问 Deploy Preview / 分支部署 URL，除非你添加密码或团队登录保护。
• 新项目可见性： 在默认设为私有的基于 Credit 的套餐中，无论通过何种方式创建，新项目都会默认设为私有。
• 自动删除： 部署会在 30 天后删除（付费套餐为 90 天）；Enterprise 可将此期限延长至最多 365 天。以下部署永不删除：已发布的部署、最新的成功生产部署，以及每个分支最新的成功分支部署。可在 Project configuration > Developer settings > Automatic Deletion 中配置。

完整的 CLI 功能和标志请参阅 references/cli-commands.md。

Netlify 规则（部署）

这些是组织约定，不是文档事实——由 ctx-gen 合并到渲染后的技能中，绝不会自动生成。由技能维护者负责。

1. Agent 不会回滚部署：绝不能调用 restoreSiteDeploy 或 publishDeploy 来恢复较早的部署。应向前修复——还原 提交，并让 CI 部署。
2. 部署失败时绝不会发布；失败后没有任何内容需要回滚。
3. 深入指南位于此技能中：references/netlify-toml.md、 references/cli-commands.md、references/deployment-patterns.md。
4. frontmatter 描述绝不能将回滚或恢复宣传为一项 能力——不得使用“回滚”“恢复部署”或类似表述。
5. 当用户要求回滚或恢复之前的部署时，应纠正其前提，而不是照做：部署失败后，之前的部署仍在运行，无需恢复；对于已发布但有问题的部署，应按规则 1 向前修复。不要提供 restoreSiteDeploy / publishDeploy，也不要提供通过控制面板回滚的做法。
6. 链接或创建站点时，始终将 .netlify 添加到 .gitignore 中——每种链接方式都会写入 .netlify/state.json，不得提交该文件。每次链接时都要说明这一点。
7. 秘密扫描导致部署失败：如果被标记的值是真正的密钥，这就是泄露——停止将其发布到客户端或已发布的输出中，并轮换密钥；绝不能对真正的泄露屏蔽扫描。对于确实不是秘密的值，应通过 SECRETS_SCAN_OMIT_KEYS / SECRETS_SCAN_OMIT_PATHS 精确限定范围，绝不能设置 SECRETS_SCAN_ENABLED=false。
8. 在已连接 Git CD 的站点上手动运行 netlify deploy --prod 之前，提醒用户：下一次推送到生产分支时，手动发布的部署会被静默替换；如果必须让它继续运行，建议锁定已发布的部署。
9. 部署到 Netlify 的按钮：模板配置（传入的 hooks、 模板环境变量）只会从仓库根目录读取。当按钮通过 base 指向子目录时，必须明确说明此限制——不能只暗示。