Netlify 部署完全指南#

核心功能#

• Git 集成：连接 GitHub, GitLab, Bitbucket 仓库，实现自动部署。
• 全球 CDN：自动将您的站点分发到全球边缘网络，提供快速访问。
• 无服务器函数：支持 Netlify Functions，轻松部署后端逻辑。
• 表单处理：内置表单处理功能，无需后端即可收集用户数据。
• 分支部署：为每个 Git 分支创建独立的部署预览。
• 免费额度：提供慷慨的免费套餐，适合个人和小型项目。

步骤 1：新建站点#

1. 登录 Netlify 控制台。
2. 点击 “New site from Git”。
3. 选择您的 Git 提供商（GitHub, GitLab, Bitbucket）并授权 Netlify 访问。
4. 选择要部署的仓库。

步骤 2：配置构建设置#

Netlify 会尝试自动检测您的项目类型并配置构建设置：

• Branch to deploy: 选择要部署的分支（通常是 main 或 master）。
• Build command: 构建命令，如 npm run build、yarn build 等。
• Publish directory: 构建输出目录，如 dist、build、public 等。

常见框架的配置示例：#

React (Create React App)

1
Build command: npm run build
2
Publish directory: build

Vue.js

1
Build command: npm run build
2
Publish directory: dist

Astro

1
Build command: npm run build
2
Publish directory: dist

Next.js (静态导出)

1
Build command: npm run build && npm run export
2
Publish directory: out

步骤 3：部署#

确认配置无误后，点击 “Deploy site”。Netlify 将开始第一次构建和部署。

自动更新#

配置完成后，每当您向指定分支推送新的提交时，Netlify 都会自动触发重新构建和部署。

步骤：#

1. 在本地构建您的项目（如运行 npm run build）。
2. 登录 Netlify 控制台。
3. 将构建输出文件夹直接拖拽到 Netlify 的部署区域。
4. Netlify 会自动上传并部署您的站点。

注意事项：#

• 这种方式不支持自动更新，每次更改都需要手动重新拖拽。
• 适合快速原型或一次性部署。

步骤 1：安装 Netlify CLI#

1
npm install -g netlify-cli

步骤 2：登录#

1
netlify login

步骤 3：初始化项目#

在项目根目录运行：

1
netlify init

步骤 4：部署#

1
# 部署到预览环境
2
netlify deploy
3

4
# 部署到生产环境
5
netlify deploy --prod

在 Netlify 控制台中配置#

1. 进入您的站点设置。
2. 点击 “Environment variables”。
3. 添加您的环境变量键值对。

在 netlify.toml 中配置#

在项目根目录创建 netlify.toml 文件：

1
[build.environment]
2
  NODE_VERSION = "18"
3
  NPM_VERSION = "8"
4

5
[context.production.environment]
6
  API_URL = "https://api.example.com"
7

8
[context.deploy-preview.environment]
9
  API_URL = "https://staging-api.example.com"

步骤：#

1. 进入站点设置的 “Domain management”。
2. 点击 “Add custom domain”。
3. 输入您的域名。
4. 根据提示配置 DNS 记录：
   • 子域名：添加 CNAME 记录指向您的 Netlify 站点 URL。
   • 根域名：添加 A 记录指向 Netlify 的 IP 地址。
5. Netlify 会自动为您的域名配置 SSL 证书。

基本用法：#

1
<form name="contact" method="POST" data-netlify="true">
2
  <p>
3
    <label>姓名: <input type="text" name="name" /></label>
4
  </p>
5
  <p>
6
    <label>邮箱: <input type="email" name="email" /></label>
7
  </p>
8
  <p>
9
    <label>消息: <textarea name="message"></textarea></label>
10
  </p>
11
  <p>
12
    <button type="submit">发送</button>
13
  </p>
14
</form>

添加验证码：#

1
<form name="contact" method="POST" data-netlify="true" data-netlify-recaptcha="true">
2
  <!-- 表单字段 -->
3
  <div data-netlify-recaptcha="true"></div>
4
  <button type="submit">发送</button>
5
</form>

1. 使用 netlify.toml 配置文件#

在项目根目录创建 netlify.toml 来管理构建和部署配置：

1
[build]
2
  publish = "dist"
3
  command = "npm run build"
4

5
[build.environment]
6
  NODE_VERSION = "18"
7

8
[[redirects]]
9
  from = "/*"
10
  to = "/index.html"
11
  status = 200

2. 配置重定向规则#

对于单页应用（SPA），配置重定向规则以支持客户端路由：

1
[[redirects]]
2
  from = "/*"
3
  to = "/index.html"
4
  status = 200

3. 优化构建性能#

• 使用缓存：Netlify 会自动缓存 node_modules。
• 设置合适的 Node.js 版本。
• 使用 netlify-plugin-cache 插件缓存其他依赖。

4. 利用分支部署#

为不同的分支配置不同的部署环境：

1
[context.production]
2
  command = "npm run build:prod"
3

4
[context.deploy-preview]
5
  command = "npm run build:preview"
6

7
[context.branch-deploy]
8
  command = "npm run build:dev"

5. 监控和分析#

• 启用 Netlify Analytics 监控站点性能。
• 使用 Netlify 的构建日志调试部署问题。
• 设置部署通知，及时了解部署状态。

Q1: 构建失败，提示找不到命令？#

解决方案：

• 检查 package.json 中是否定义了构建脚本。
• 确认构建命令在 Netlify 配置中正确设置。
• 检查 Node.js 版本是否兼容，可在 netlify.toml 中指定版本。

Q2: 单页应用刷新页面出现 404 错误？#

解决方案： 添加重定向规则到 netlify.toml：

1
[[redirects]]
2
  from = "/*"
3
  to = "/index.html"
4
  status = 200

Q3: 环境变量在客户端无法访问？#

解决方案：

• 确保环境变量名有正确的前缀（如 React 需要 REACT_APP_）。
• 检查变量是否在正确的部署上下文中配置。
• 重新部署以应用新的环境变量。

Q4: 表单提交后没有收到数据？#

解决方案：

• 确保表单包含 data-netlify="true" 属性。
• 检查表单的 name 属性是否设置。
• 在 Netlify 控制台的 “Forms” 部分查看提交的数据。

Q5: 自定义域名配置后无法访问？#

解决方案：

• 检查 DNS 记录是否正确配置。
• 等待 DNS 传播完成（通常需要几分钟到几小时）。
• 确保域名没有被其他服务占用。