Netlify：前端部署全攻略

为什么需要 Netlify：从手动上线到 Push 即发布

传统静态站交付链路很长：买云服务器或对象存储、配置 Nginx、写上传脚本，每次发版要么覆盖式上传、要么登录服务器手工操作；出问题时没有版本快照，回滚靠手工恢复备份，域名与 HTTPS 证书还要单独维护。对 AI 团队更麻烦——模型 Demo、Chatbot UI 一周改好几版，评审只能靠截图，联调环境难以共享。

Netlify 把整条链路折叠成「连接仓库 → 自动构建 → 原子发布」三步：push 到生产分支触发构建；pull request 自动生成独立预览 URL；发布是整体快照的原子切换（新版本文件全部就绪后一次性生效，访问者永远不会看到半新半旧的版本），可一键回滚到任意历史部署。HTTPS 证书、CDN（内容分发网络，把静态文件缓存到全球边缘节点加速访问）、环境变量、表单、函数全部内置，不需要自己运维任何服务器。

与 Vercel 优先为 Next.js 做深度优化不同，Netlify 对 Vite、Astro、Hugo、Docusaurus、React 等任意静态框架一视同仁，配置靠仓库里的 netlify.toml 声明，适合框架不统一、需要表单与身份能力、重视预览评审的工程化团队。

安装与环境配置：3 步就绪

Netlify 是 SaaS 平台，网页端无需安装任何东西；CLI 仅用于命令行部署与本地开发模拟。

步骤一：注册并连接 Git 账号。 打开 app.netlify.com，用邮箱注册，或直接用 GitHub 账号 OAuth 登录（推荐，省去后续仓库授权）。

步骤二：安装 CLI。 本机需有 Node.js 18 及以上版本，执行 npm install -g netlify-cli；macOS/Linux 也可用 brew install netlify-cli。

步骤三：登录与验证。 执行 netlify login，浏览器会打开授权页完成登录；netlify status 可查看当前账号与已关联站点。

无需手动配置 API Token：CLI 登录后会把鉴权信息保存在本机 ~/.netlify 目录，之后 netlify 系列命令自动携带身份。

# 1. 全局安装 Netlify CLInpm install -g netlify-cli # 2. 验证安装netlify --version # 3. 浏览器授权登录netlify login # 4. 查看账号状态netlify status

快速上手：15 分钟跑通 Git 导入部署

目标：把任意一个本地前端项目在 15 分钟内变成线上可访问的 HTTPS 站点。思路是先用网页控制台把「Git 导入 → 构建 → 发布」全流程跑通，再切到 CLI 进入「push 即发布」的日常循环。

1. 本地项目初始化 Git 并推送到 GitHub：依次执行 git init、git add .、git commit -m "init"、git push（仓库需对 Netlify 可见）。

2. 登录 app.netlify.com → 右上角「Add new site」→「Import an existing project」→ 选择 GitHub 并完成授权 → 找到目标仓库点击导入。

3. 在 Build settings 中填写构建命令（如 npm run build、hugo、mkdocs build）与发布目录（如 dist、public、site），点击「Deploy site」。

4. 等待约 1-2 分钟，页面出现形如 https://{随机名}.netlify.app 的正式地址；此后每次 push 到生产分支都会自动重新构建。

5. 进入日常循环：本地修改 → git push → 在 Site configuration → Deploys 页面查看构建日志与线上地址。

6. 切换到命令行发布：在仓库根目录执行 netlify init 关联站点，之后 netlify deploy --prod --build 直接发生产。

说明：命令行发布需先 netlify init 建立站点关联；CI 场景可跳过交互，直接用 netlify deploy --prod --build --dir dist 指定产物目录。进阶技巧：把 netlify.toml 提交进仓库后，构建命令、发布目录与重定向规则随代码版本化，团队成员不再需要在后台手动改配置。

核心能力详解：5 大支柱

支柱一：持续部署与部署预览。 Git 集成下产生三类部署上下文：生产（production）、分支（branch）与预览（deploy-preview）。每个 pull request 会自动生成唯一预览 URL，可在后台开启密码保护后发给产品评审；分支部署则用于预发布环境。每类上下文可以拥有独立的环境变量，例如预览环境指向测试 API、生产环境指向正式 API。

支柱二：netlify.toml 声明式配置。 构建、重定向、响应头、环境变量、插件全部可以用一个文件声明并随仓库版本化。常见写法：

重定向规则既支持 301/302 跳转（如 /old → /new），也支持 status = 200 的反向代理式转发，常用于把前端路由交给 SPA 应用处理。

支柱三：Functions 与 Edge Functions 两级无服务器能力。 把函数文件放进仓库的 netlify/functions 目录即自动部署，官方运行时支持 Node.js、Go、Rust；同步函数最长运行 26 秒，长时间任务请用后台函数（Background Functions，最长 15 分钟）。函数 v2 API 示例：

Edge Functions 基于 Deno 运行时在 CDN 边缘执行，典型用途是地域分流、A/B 测试、请求级鉴权与响应头改写，延迟比函数回源更低。

支柱四：表单与身份认证。 HTML 表单加 data-netlify="true" 属性后，提交会自动进入 Netlify 后台，可配置邮件通知或 Webhook（免费套餐每站每月 100 次提交）；Identity 提供注册、登录、角色体系，基于开源的 GoTrue 服务，前端接入官方 Widget 即可使用，适合活动页留资、Demo 试用申请等场景。

支柱五：交付保障。 自动签发与续期 Let's Encrypt 免费证书；自定义域名绑定后自动切换 HTTPS；每次部署都是不可变快照，可在 Deploys 列表一键回滚；Image CDN 支持在图片 URL 上附加 ?nf_resize=fit&w=400 之类参数即时缩放，省去本地图片处理流水线。

[build]  command = "npm run build"  publish = "dist" [[redirects]]  from = "/api/*"  to = "https://api.example.com/:splat"  status = 200

// netlify/functions/hello.mjsexport default async (request, context) => {  return Response.json({ message: "Hello from Netlify" })}

生产部署与监控：从上线到运维

部署方式一：生产分支 + 预览评审流。 在 Site configuration → Build & deploy → Deploy contexts 中把 main 设为生产分支并开启 Deploy Previews。开发流程为「功能分支 push → 生成预览链接 → 评审 → merge 到 main → 自动发生产」；预览与生产分别配置环境变量（如 API_BASE_URL），避免测试环境误连生产数据库。

部署方式二：CLI 嵌入 CI 流水线。 在 GitHub Actions 等 CI 中调用 npx netlify-cli deploy --prod --build，身份通过 NETLIFY_AUTH_TOKEN 环境变量注入（用 netlify login 生成的 token 配置到 CI Secrets）。单仓库多应用时用 --dir 指定产物目录、--filter 指定具体服务，避免互相干扰。

可观测性： 构建失败排查看 Deploys 页的构建日志；函数运行情况查看 Functions 日志；全局服务状态实时查 status.netlify.com；在 Site configuration → Notifications 中配置构建成功/失败通知（邮件、Slack、Webhook）。生产上线前建议：用 NODE_VERSION 固定构建环境 Node 版本、开启部署通知、把回滚演练（Deploys 列表一键回退）纳入发布检查清单。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>本地构建正常、Netlify 上失败：多为 Node 版本不一致。构建镜像默认版本与本地可能不同，须在 netlify.toml 的 [build.environment] 或后台环境变量中固定 NODE_VERSION（或用 .nvmrc），并提交 package-lock.json 保证依赖一致。</li><li>netlify deploy 默认是草稿而非生产：不传 --prod 时只发布为预览 URL，需在后台手动 Publish 才生效，CI 脚本里务必显式使用 netlify deploy --prod --build，否则会出现「部署成功」但线上无变化。</li><li>密钥被前端打包泄漏：构建期所有环境变量对构建进程可见，凡在前端代码中被引用的变量都会打进产物包。服务端密钥（如 LLM API Key）只能在 Functions/Edge Functions 内读取，前端改用独立命名（如 PUBLIC_ 前缀）的公共变量。</li></ul>

版本迭代

Netlify 是 SaaS 平台，没有传统意义的软件版本号，功能通过官方 Changelog 按周持续发布。下表以其重大功能里程碑为版本节点，展示从「静态托管」到「具备无服务器与边缘能力的应用平台」的演进主线（截至训练数据，平台仍按周迭代，最新条目以官方 Changelog 为准）。

AI 应用场景

常见误区

面试题