Skip to content
返回部署

Netlify 持续集成部署

基于 Git 的部署、构建插件与 CI/CD 管线，含 Netlify Functions 与部署预览。

CI/CD进阶

为什么

Netlify 的 git 连接工作流为每个 PR 提供隔离预览部署及独立 URL，支持合并前利益相关者评审。构建插件扩展管线（Lighthouse、a11y、包分析）无需改代码，部署上下文允许按分支变配置。

DORA 2024 DevOps 状态报告显示精英团队部署频率比低绩效团队高 973 倍。带自动化测试的 CI/CD 管道将变更失败率降至 5-15%，而手动部署为 40-60%。

何时使用

需要每 PR 预览部署、静态旁 serverless 函数和内置表单处理无后端时用 Netlify。需要长时运行服务器或容器时跳过（用 Fly.io 或 Railway）。

如何做

1. 连接仓库 — app.netlify.com → 添加站点 → 从 GitHub/GitLab/Bitbucket 导入 2. 配置构建 — netlify.toml 或面板：构建命令、发布目录、函数目录 3. 部署上下文 — [context.production] / [context.deploy-preview] 按环境覆盖 4. Functions — /netlify/functions/*.ts 自动部署为 serverless，从 @netlify/functions 导入 5. 构建插件 — netlify.toml [[plugins]] 加 @netlify/plugin-lighthouse、plugin-sitemap 6. CI 集成 — push 时 Netlify 构建；外部 CI 用 netlify deploy --prod --auth=$TOKEN 7. 表单 — 给 <form> 加 netlify 属性，提交进面板 + 可 POST 到 webhook 8. 重定向/头 — _redirects 文件或 netlify.toml [[redirects]] 做 SPA 回退、安全头

示例

# netlify.toml — 完整配置 [build] command = "npm run build" publish = "dist" functions = "netlify/functions" [build.environment] NODE_VERSION = "20" NPM_FLAGS = "--legacy-peer-deps" # 按上下文覆盖 [context.deploy-preview] command = "npm run build:preview" [context.production] command = "npm run build:prod" # 构建插件 [[plugins]] package = "@netlify/plugin-lighthouse" [plugins.inputs] threshold = 0.85 [[plugins]] package = "@netlify/plugin-sitemap" # 重定向 + 头 [[redirects]] from = "/*" to = "/index.html" status = 200 force = false conditions = {Role = ["admin"]} [[headers]] for = "/*" [headers.values] X-Frame-Options = "DENY" Content-Security-Policy = "default-src 'self'" // netlify/functions/api.ts — serverless 函数 import { handler } from "@netlify/functions"; export const handler = handler(async (event) => { return { statusCode: 200, body: JSON.stringify({ ok: true }) }; });

常见问题

  • ⚠本地构建通过但 Netlify 失败 — Node 版本不匹配，在 toml 设 NODE_VERSION
  • ⚠Functions 生产 502 — 忘记导出 handler，或用了运行时不支持的 Node API
  • ⚠插件拖慢构建 5 分钟 — Lighthouse 插件每次部署都跑，仅限生产
  • ⚠表单提交未出现 — <form> 缺 netlify 属性或 name，或 SPA 重渲染它

最佳实践

  • ✓netlify.toml 固定 NODE_VERSION — 别依赖 Netlify 默认，它会变
  • ✓昂贵插件限生产上下文 — 预览无需完整 Lighthouse 审计
  • ✓用部署预览做 QA — 合并前与利益相关者分享预览 URL
  • ✓仅在需要时设 NPM_FLAGS=--legacy-peer-deps — 它掩盖真实依赖冲突

常见问题解答

如何从 GitHub Actions 触发部署而非 Netlify git 集成？

用 netlify-actions/deploy action 配 NETLIFY_AUTH_TOKEN 密钥。在站点设置中禁用 Netlify 内置 git 构建。避免每次推送双重构建。

为什么 Netlify Functions 超时？

免费计划 10s 超时（Pro 26s）。长任务移到后台函数（异步，立即返回）或专用 worker。Functions 标签查函数日志。

Netlify CI 中如何用环境变量？

站点设置中设置，或 netlify.toml [build.environment]。密钥仅用面板——绝不提交含密钥的 netlify.toml。按部署上下文（production、deploy-preview）作用域变量。

为什么 SPA 刷新返回 404？

客户端路由需重定向规则。加 public/_redirects 文件写 /* /index.html 200。没有它 Netlify 在任何深链刷新时返回 404 页。

如何取消卡住的部署？

Deploys 标签点部署再 Stop deploy。为防未来卡构建，netlify.toml 设超时（[build] timeout = 300）。卡构建通常意味无限循环或挂起 postinstall。