构建钩子 #

什么是构建钩子？ #

构建钩子（Build Hooks）是 Netlify 提供的 HTTP 端点，允许你通过 HTTP 请求触发站点构建。

text 
外部服务 ──HTTP POST──▶ Build Hook URL ──▶ 触发构建

创建构建钩子 #

控制台创建 #

text 
Site settings → Build & deploy → Build hooks → Add build hook

配置选项：

  • Hook 名称：用于识别
  • 触发分支：选择要构建的分支

创建后获得 #

text 
https://api.netlify.com/build_hooks/YOUR_HOOK_ID

使用构建钩子 #

基本用法 #

bash 
curl -X POST https://api.netlify.com/build_hooks/YOUR_HOOK_ID

带参数触发 #

bash 
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"branch": "staging"}' \
  https://api.netlify.com/build_hooks/YOUR_HOOK_ID

触发特定分支 #

bash 
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"branch": "feature/new-design"}' \
  https://api.netlify.com/build_hooks/YOUR_HOOK_ID

应用场景 #

1. CMS 触发构建 #

当内容管理系统（CMS）内容更新时自动触发构建：

Contentful 示例：

text 
Contentful Webhook Settings:
- URL: https://api.netlify.com/build_hooks/YOUR_HOOK_ID
- Triggers: Entry publish, Entry unpublish

Strapi 示例：

javascript 
// config/server.js
module.exports = {
  webhooks: {
    netlify: {
      url: 'https://api.netlify.com/build_hooks/YOUR_HOOK_ID',
      headers: {},
      events: ['entry.create', 'entry.update', 'entry.delete']
    }
  }
}

2. 定时构建 #

使用外部服务定时触发构建：

GitHub Actions 定时构建：

yaml 
# .github/workflows/scheduled-build.yml
name: Scheduled Build
on:
  schedule:
    - cron: '0 0 * * *'  # 每天 UTC 0点

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Netlify Build
        run: curl -X POST ${{ secrets.NETLIFY_BUILD_HOOK }}

cron-job.org 配置：

text 
URL: https://api.netlify.com/build_hooks/YOUR_HOOK_ID
Schedule: 0 0 * * *
Method: POST

3. 多仓库触发 #

当一个仓库更新时，触发另一个仓库的构建：

yaml 
# .github/workflows/trigger-build.yml
name: Trigger Site Build
on:
  push:
    branches: [main]

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Netlify Build
        run: curl -X POST ${{ secrets.NETLIFY_BUILD_HOOK }}

4. 数据更新触发 #

数据库或 API 数据变化时触发构建：

javascript 
// 数据更新后触发构建
async function onDataUpdate() {
  await fetch('https://api.netlify.com/build_hooks/YOUR_HOOK_ID', {
    method: 'POST'
  })
}

部署通知 #

配置通知 #

text 
Site settings → Build & deploy → Deploy notifications

支持的通知类型 #

类型 说明
Email 邮件通知
Slack Slack 消息
Webhook 自定义 HTTP 回调

Webhook 通知 #

配置 Webhook 接收部署事件：

json 
{
  "id": "12345",
  "site_id": "abc123",
  "build_id": "def456",
  "state": "ready",
  "name": "my-site",
  "url": "https://my-site.netlify.app",
  "ssl_url": "https://my-site.netlify.app",
  "admin_url": "https://app.netlify.com/sites/my-site",
  "deploy_url": "https://12345--my-site.netlify.app",
  "branch": "main",
  "commit_ref": "abc123",
  "commit_url": "https://github.com/user/repo/commit/abc123",
  "skipped": false,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z",
  "deploy_ssl_url": "https://12345--my-site.netlify.app"
}

Slack 通知 #

text 
Site settings → Build & deploy → Deploy notifications → Add notification → Slack integration

配置 Slack Webhook URL 后，部署状态会发送到指定频道。

构建状态 API #

获取站点信息 #

bash 
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.netlify.com/api/v1/sites/YOUR_SITE_ID

获取部署列表 #

bash 
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.netlify.com/api/v1/sites/YOUR_SITE_ID/deploys

获取特定部署 #

bash 
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.netlify.com/api/v1/deploys/DEPLOY_ID

锁定部署 #

bash 
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.netlify.com/api/v1/deploys/DEPLOY_ID/lock

解锁部署 #

bash 
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.netlify.com/api/v1/deploys/DEPLOY_ID/unlock

构建钩子安全 #

保护钩子 URL #

构建钩子 URL 是公开的，任何人知道 URL 都能触发构建。

最佳实践：

  1. 不要在公开代码中暴露钩子 URL
  2. 使用环境变量存储钩子 URL
  3. 定期轮换钩子（删除重建）

使用环境变量 #

bash 
# GitHub Secrets
NETLIFY_BUILD_HOOK=https://api.netlify.com/build_hooks/xxx
yaml 
# GitHub Actions
- name: Trigger Build
  run: curl -X POST ${{ secrets.NETLIFY_BUILD_HOOK }}

忽略构建 #

配置忽略规则 #

toml 
[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ."

常用忽略规则 #

toml 
# 只在 src 目录变化时构建
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ./src"

# 只在特定文件变化时构建
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF -- '*.js' '*.css'"

# 排除某些目录
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF -- . ':!docs' ':!README.md'"

构建队列管理 #

查看构建状态 #

text 
Deploys → 查看当前构建状态

取消构建 #

text 
Deploys → 点击正在进行的部署 → Cancel deploy

并发构建限制 #

方案 并发构建数
Free 1
Pro 3
Business 自定义

构建钩子 vs Git 触发 #

特性 Build Hook Git Push
触发方式 HTTP 请求 Git 推送
适用场景 外部系统、定时任务 代码更新
分支选择 可指定 固定
构建日志 有 有

完整示例 #

CMS + Netlify 构建流程 #

text 
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CMS 更新   │ ──▶ │  Webhook    │ ──▶ │  Netlify    │
│   内容       │     │  触发构建    │     │  自动构建    │
└─────────────┘     └─────────────┘     └─────────────┘

配置步骤 #

  1. 在 Netlify 创建构建钩子

    text 
    Site settings → Build & deploy → Build hooks → Add build hook

  2. 在 CMS 配置 Webhook

    text 
    Webhook URL: https://api.netlify.com/build_hooks/YOUR_HOOK_ID
Method: POST

  3. 测试触发

    bash 
    curl -X POST https://api.netlify.com/build_hooks/YOUR_HOOK_ID

下一步 #

掌握了构建钩子后，继续学习 域名绑定 为你的站点配置自定义域名！

最后更新：2026-03-28