netlify-integration

Netlify 集成

何时使用此技能

在以下情况下使用此技能：

部署与配置：

• 将 Next.js 应用部署到 Netlify
• 配置 netlify.toml 中的构建设置、函数、重定向或标头
• 在 Netlify Dashboard 或 CLI 中设置环境变量
• 配置通过 Git（GitHub、GitLab、Bitbucket）进行持续部署

函数开发：

• 创建 Netlify 无服务器函数
• 处理 Webhook（Twilio、Telnyx、Stripe 等）
• 调试函数超时问题（免费层级限制为 10 秒，Pro 为 26 秒）
• 为长时间运行的任务实现后台处理

故障排查：

• 修复 Webhook 超时错误（尤其是短信/电话应用）
• 调试“Function not found”（404）错误
• 解决环境变量问题
• 修复构建失败或部署错误

短信/电话项目：

• 开发 Twilio-Aldea 这类处理短信 Webhook 的项目
• 实现即时确认 Webhook + 后台处理
• 验证 Webhook 签名（Twilio、Telnyx）

快速参考

1. 基本的 Netlify 函数处理程序

import type { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";

export const handler: Handler = async (
  event: HandlerEvent,
  context: HandlerContext
) => {
  try {
    const body = JSON.parse(event.body || "{}");

    // Process request
    console.log("Request received:", body);

    return {
      statusCode: 200,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ success: true }),
    };
  } catch (error) {
    console.error("Error:", error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: "Internal server error" }),
    };
  }
};

2. 立即响应的 Webhook（关键模式）

解决 60% 的消息丢失问题——立即返回 200，异步处理：

export const handler: Handler = async (event, context) => {
  // Validate webhook signature
  const isValid = validateWebhook(event);
  if (!isValid) {
    return { statusCode: 401, body: "Unauthorized" };
  }

  // IMMEDIATE: Return 200 OK (< 200ms)
  const response = {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };

  // BACKGROUND: Process async (don't await)
  processWebhookAsync(event.body).catch(console.error);

  return response;
};

3. Next.js 必备的 netlify.toml

[build]
  command = "npm run build"
  publish = ".next"

[build.environment]
  NODE_VERSION = "18"
  NEXT_TELEMETRY_DISABLED = "1"

# OpenNext adapter auto-detects Next.js — no plugin entry needed.
# Legacy: @netlify/plugin-nextjs is replaced by @opennextjs/netlify.

[functions]
  directory = ".netlify/functions"
  node_bundler = "esbuild"

# API rewrites
[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200
  force = true

# Security headers
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

4. 设置环境变量（CLI）

前提条件——先关联项目：

# Option 1: Interactive linking
netlify link

# Option 2: Manual linking (create .netlify/state.json)
mkdir -p .netlify
echo '{"siteId":"YOUR-SITE-ID-HERE"}' > .netlify/state.json

# Find your site ID
netlify sites:list  # Shows all sites with their IDs

# Verify link worked
netlify status

管理环境变量：

# Set single variable (use --force to skip confirmation)
netlify env:set VARIABLE_NAME value
netlify env:set VARIABLE_NAME "value with spaces" --force

# Set for specific context (production, deploy-preview, branch-deploy, dev)
netlify env:set VARIABLE_NAME value --context production

# Import from .env file
netlify env:import .env.production

# List all variables
netlify env:list

# Get specific variable value
netlify env:get VARIABLE_NAME

# Delete variable
netlify env:unset VARIABLE_NAME

# Clone variables from another site
netlify env:clone --from OTHER_SITE_ID

批量添加示例（从 shell 执行）：

# Add multiple env vars in sequence
netlify env:set API_KEY "sk-xxx" --force
netlify env:set ENABLE_FEATURE "true" --force
netlify env:set NEXT_PUBLIC_APP_URL "https://myapp.netlify.app" --force

**注意：**添加或更改环境变量后，可能需要触发重新部署，才能让更改在生产环境中生效。

5. 配置函数超时

[functions]
  directory = ".netlify/functions"
  timeout = 10  # Default for all functions

# Increase timeout for specific function
[[functions."webhook"]]
  timeout = 26  # Max for Pro tier (10s for free)

6. 用于签名验证的原始请求体解析

这是验证 Twilio/Telnyx Webhook 签名的关键步骤：

export const config = {
  api: {
    bodyParser: false,  // Disable Next.js body parsing
  },
};

async function readRawBody(req: NextApiRequest): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    let data = '';
    req.setEncoding('utf8');
    req.on('data', (chunk) => { data += chunk; });
    req.on('end', () => resolve(data));
    req.on('error', reject);
  });
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const rawBody = await readRawBody(req);

  // Validate signature with raw body
  const isValid = validateSignature(rawBody, req.headers['x-twilio-signature']);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
}

7. 数据库错误日志记录模式

export const handler: Handler = async (event) => {
  try {
    await processMessage(data);
    return { statusCode: 200, body: 'Success' };
  } catch (error: unknown) {
    const err = error instanceof Error ? error : new Error(String(error));
    console.error('[Function] Error:', err);

    // Log to database for visibility
    await supabase.from('processing_errors').insert({
      error_message: err.message,
      error_stack: err.stack,
      created_at: new Date().toISOString(),
    });

    return { statusCode: 500, body: `Error: ${err.message}` };
  }
};

8. 连接池模式

// Reuse connections across function invocations
let supabaseClient: any = null;

function getSupabaseClient() {
  if (!supabaseClient) {
    supabaseClient = createClient(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_SERVICE_KEY!
    );
  }
  return supabaseClient;
}

export const handler: Handler = async (event, context) => {
  const supabase = getSupabaseClient();
  // Use cached client - reduces cold start time
};

9. 动态检测基础 URL

function getBaseUrl(req: NextApiRequest): string {
  const proto = (req.headers['x-forwarded-proto'] as string) || 'https';
  const host = (req.headers['x-forwarded-host'] as string) || (req.headers.host as string);
  return `${proto}://${host}`;
}

// Works in production, preview deploys, and localhost
const baseUrl = getBaseUrl(req);
const backgroundUrl = `${baseUrl}/.netlify/functions/background`;

10. 使用 Zod 验证输入

import { z } from "zod";

const WebhookSchema = z.object({
  from: z.string().min(10).max(15),
  to: z.string().min(10).max(15),
  body: z.string().min(1).max(1600),
  messageId: z.string().uuid(),
});

export const handler: Handler = async (event, context) => {
  try {
    const data = JSON.parse(event.body || "{}");
    const validated = WebhookSchema.parse(data);

    await processMessage(validated);
    return { statusCode: 200, body: JSON.stringify({ success: true }) };
  } catch (error) {
    if (error instanceof z.ZodError) {
      return {
        statusCode: 400,
        body: JSON.stringify({ error: "Validation failed", details: error.errors }),
      };
    }
    throw error;
  }
};

核心概念

Netlify 函数

• 在 AWS Lambda 上运行的无服务器函数
• 位于 .netlify/functions/ 目录中
• 支持 Node.js、TypeScript、Go
• 超时限制：10 秒（免费层级）、26 秒（Pro 层级）
• 后台函数：文件名以 -background.ts 为后缀，可获得 15 分钟超时

netlify.toml

• 用于 Netlify 部署的基于文件的配置
• 放在仓库根目录
• 控制构建设置、函数、重定向和标头
• 支持特定上下文配置（production、deploy-preview、branch-deploy）

环境变量

• 服务器端：通过 process.env.VARIABLE_NAME 访问（名称不限）
• 客户端：必须添加 NEXT_PUBLIC_ 前缀才能向浏览器公开
• 在 Netlify Dashboard（Site Settings → Environment Variables）中设置，或通过 CLI 设置
• 切勿将 .env 文件提交到 Git

Webhook 超时问题

• 短信服务提供商（Twilio/Telnyx）要求在 10 秒内收到响应
• AI 处理需要 15-25 秒
• 解决方案：立即返回 200，在后台函数中异步处理
• 结果：超时率降至 0%（此前失败率为 60%）

后台函数

• 通过文件名自动识别：function-name-background.ts
• 15 分钟超时（普通函数为 10-26 秒）
• 非常适合长时间运行的 AI 处理、数据处理等任务
• 无需额外配置

Next.js 与 Netlify 集成

• 由开源 OpenNext 适配器（@opennextjs/netlify）提供支持；它取代了旧版 @netlify/plugin-nextjs，成为规范方案
• 支持 Next.js 13.5+ 至 16，包括 App Router、Server Components 和 Streaming
• 自动处理 ISR、SSR、静态生成和精细化边缘缓存
• API 路由会自动转换为无服务器函数
• 自定义函数放在 .netlify/functions/ 中（与 pages/api/ 分开）
• 除非在 package.json 中固定版本，否则适配器会在每次构建时自动更新

参考文件

核心配置

• references/netlify_config.md - 完整的 netlify.toml 参考，包含所有配置选项（build、functions、redirects、headers、contexts）
• references/environment_variables.md - 环境变量管理、作用域、客户端与服务端、批量导入/导出

函数开发

• references/functions_best_practices.md - 函数模式：异步处理、错误处理、安全、数据库操作、监控
• references/production-patterns.md - 来自 Twilio-Aldea 生产环境的 8 种真实场景模式（webhook 超时、后台处理、错误日志记录）

故障排查

• references/debugging.md - 全面的调试指南，涵盖构建失败、函数错误、webhook 问题、数据库问题

Netlify 官方文档

• references/official-docs/functions.md - 完整的 Netlify Functions 指南，涵盖处理程序类型、事件结构、部署
• references/official-docs/environment-variables.md - 环境变量配置、作用域、运行时访问
• references/official-docs/netlify-toml.md - 基于文件的配置参考
• references/official-docs/nextjs.md - 通过 OpenNext 适配器在 Netlify 上运行 Next.js：App Router、ISR、SSR、skew protection、图像优化

代码示例

• assets/examples/webhook-function.ts - 使用即时响应模式的 webhook 处理程序
• assets/examples/background-function.ts - 用于长时间运行任务处理的后台函数
• assets/examples/netlify.toml - 带注释的完整配置示例
• assets/examples/api-route.ts - 使用原始请求体解析和签名验证的 Next.js API 路由

项目专属

• references/twilio_aldea_specific.md - Twilio-Aldea 短信平台专属模式（webhook 处理、会话管理、统一的提供商接口）

GitHub 仓库（新增）

references/github/README.md

来自 GitHub 的 Netlify CLI 官方 README（netlify/cli，1,752 个星标）

references/github/issues.md

12 个展示常见问题及解决方案的 GitHub issue：

• 构建失败和部署错误
• 环境变量问题
• 函数超时问题
• 重定向和路由配置
• 本地开发环境设置

references/github/CHANGELOG.md

完整版本历史，包含破坏性变更和新功能

references/github/releases.md

1,203 个 GitHub release，附详细 CLI 更新日志

references/github/file_structure.md

仓库结构（871 个文件），展示 CLI 源代码组织方式

使用此技能

新手入门

如果你刚开始使用 Netlify，请从这里开始：

1. 部署你的第一个应用：

   • 查看下方的“初始部署（Git 集成）”部分
   • 按照分步工作流操作
   • 将快速参考 #3 作为 netlify.toml 初始模板

2. 了解基础知识：

   • 阅读 references/official-docs/functions.md，了解 Netlify Functions 基础知识
   • 查看快速参考（#1、#4）中的简单示例
   • 阅读 references/official-docs/environment-variables.md，了解环境配置

3. 创建你的第一个函数：

   • 复制基础函数处理程序示例（#1）
   • 将其放入 .netlify/functions/hello.ts
   • 部署后，在 https://yoursite.netlify.app/.netlify/functions/hello 测试

面向中级用户

已熟悉 Netlify 基础知识：

1. 实现生产模式：

   • 阅读 references/production-patterns.md，了解真实场景示例
   • 如果要处理 Webhook，请实现模式 1（立即响应 + 后台处理）
   • 查看模式 5（将错误日志记录到数据库），以改进监控

2. 优化设置：

   • 添加连接池（#8），减少冷启动
   • 实现恰当的错误处理，并将日志记录到数据库（#7）
   • 使用 Zod 添加输入验证（#10）

3. 处理复杂场景：

   • 学习原始请求体解析（#6），以验证 Webhook 签名
   • 在 netlify.toml 中配置特定上下文的构建
   • 设置 API 调用的代理模式（production-patterns.md 中的模式 4）

面向高级用户

构建可用于生产环境的无服务器应用：

1. 掌握 Webhook 处理：

   • 深入学习 references/production-patterns.md 中的模式 1（Webhook 超时解决方案）
   • 为 Twilio/Telnyx Webhook 实现签名验证
   • 设计多函数架构（API 路由 + 后台函数）

2. 性能优化：

   • 学习 references/functions_best_practices.md 中的冷启动优化技术
   • 为大型依赖项实现延迟加载
   • 适当配置函数内存和超时时间

3. 高级调试：

   • 使用结构化日志模式，改进可观测性
   • 实现性能指标跟踪
   • 设置全面的错误日志记录，并将日志持久化到数据库

4. 多环境设置：

   • 配置特定上下文的环境（生产、预发布、开发）
   • 管理不同上下文中的环境变量
   • 实现功能开关和 A/B 测试模式

常见工作流

将 Next.js 应用部署到 Netlify

1. 准备代码库：

   # Add netlify.toml (use Quick Reference #3 as template)
   # Add .env.example with all required variables
   git add netlify.toml .env.example
   git commit -m "Add Netlify configuration"
   git push origin main
   

2. 连接到 Netlify：

   • 访问 Netlify Dashboard → “Add new site” → “Import an existing project”
   • 选择 Git 提供商和代码库
   • 通过 netlify.toml 自动检测构建设置

3. 设置环境变量：

   netlify env:set VARIABLE_NAME value
   # Or use Netlify Dashboard: Site Settings → Environment Variables
   

4. 部署：

   • 推送到 Git 时自动部署，或手动运行：netlify deploy --prod

修复 Webhook 超时问题

**症状：**60% 的消息丢失，出现 504 Gateway Timeout 错误

解决方案：

1. 确认处理是否需要超过 10 秒
2. 实现立即响应模式（快速参考 #2）
3. 创建后缀为 -background.ts 的后台函数
4. 将长时间运行的处理移至后台函数
5. 在本地使用 netlify dev 测试

参见：references/production-patterns.md 中的模式 1，了解完整实现

调试函数错误

1. 检查函数日志：

   netlify functions:log function-name --stream
   

2. 添加结构化日志：

   console.log(JSON.stringify({
     timestamp: new Date().toISOString(),
     level: "error",
     message: "Error details",
     context: { requestId: context.requestId }
   }));
   

3. 在本地测试：

   netlify dev
   # Test at http://localhost:8888/.netlify/functions/function-name
   

4. 查看常见问题：

   • 查看 references/debugging.md 中全面的故障排除指南

版本历史

• v2.1（2026-04-21）- 针对 OpenNext adapter 更新（取代旧版 @netlify/plugin-nextjs），支持 Next.js 16，并提供细粒度边缘缓存
• v2.0（2025-11-01）- 增补 Netlify 官方文档、来自 Twilio-Aldea 的生产模式、TypeScript 示例、Webhook 超时解决方案，以及全面的 Next.js 集成指南。添加了从真实生产代码中提取的 10 个实用快速参考示例。
• v1.0 - 初始技能版本，包含部署工作流、配置、函数开发和调试

其他资源

官方文档：

• Netlify Functions
• Netlify 上的 Next.js
• 环境变量

Netlify CLI：

• 安装：npm install -g netlify-cli
• 登录：netlify login
• 文档：netlify help

辅助脚本：

• scripts/check_deployment.sh - 检查部署状态和运行状况
• scripts/setup_env_vars.sh - 批量配置环境变量
• scripts/test_function_locally.sh - 在本地测试 Netlify 函数