inngest-setup

Inngest 设置

此技能用于从零开始在 TypeScript 项目中设置 Inngest，涵盖安装、客户端配置、连接模式和本地开发。

这些技能面向 TypeScript。 对于 Python 或 Go，请参阅 Inngest 文档，了解针对相应语言的指导。核心概念适用于所有语言。

前提条件

• Node.js 18+（建议使用 Node.js 22.4+ 以支持 WebSocket）
• TypeScript 项目
• 包管理器（npm、yarn、pnpm 或 bun）

第 1 步：安装 Inngest SDK

在项目中安装 inngest npm 包：

npm install inngest
# or
yarn add inngest
# or
pnpm add inngest
# or
bun add inngest

第 2 步：创建 Inngest 客户端

创建一个共享客户端文件，供整个代码库导入：

// src/inngest/client.ts
import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-app" // Unique identifier for your application (hyphenated slug)
});
// IMPORTANT: v4 defaults to Cloud mode. For local dev, set INNGEST_DEV=1 env var.
// Without it, your serve endpoint will return 500 ("In cloud mode but no signing key").
// In production, set INNGEST_SIGNING_KEY (required for Cloud mode).

关键配置选项

• id（必填）：应用的唯一标识符。使用带连字符的标识名，例如 "my-app" 或 "user-service"
• eventKey：用于发送事件的事件密钥（建议使用 INNGEST_EVENT_KEY 环境变量）
• env：Branch Environments 的环境名称
• isDev：强制启用 Dev 模式（true）或 Cloud 模式（false）。v4 默认使用 Cloud 模式，因此本地开发时请设置 INNGEST_DEV=1 环境变量。切勿在源代码中将 isDev: true 硬编码，否则会导致生产环境静默故障。始终使用环境变量。
• signingKey：生产环境的签名密钥（建议使用 INNGEST_SIGNING_KEY 环境变量）。在 v4 中，此配置从 serve() 移至客户端
• signingKeyFallback：用于密钥轮换的备用签名密钥（建议使用 INNGEST_SIGNING_KEY_FALLBACK 环境变量）
• baseUrl：自定义 Inngest API 基础 URL（建议使用 INNGEST_BASE_URL 环境变量）
• logger：自定义日志记录器实例（例如 winston、pino），可在函数上下文中启用 logger
• middleware：中间件数组（参见 inngest-middleware 技能）

使用 eventType() 声明类型化事件

import { Inngest, eventType } from "inngest";
import { z } from "zod";

const signupCompleted = eventType("user/signup.completed", {
  schema: z.object({
    userId: z.string(),
    email: z.string(),
    plan: z.enum(["free", "pro"])
  })
});

const orderPlaced = eventType("order/placed", {
  schema: z.object({
    orderId: z.string(),
    amount: z.number()
  })
});

export const inngest = new Inngest({ id: "my-app" });

// Use event types as triggers for full type safety:
inngest.createFunction(
  { id: "handle-signup", triggers: [signupCompleted] },
  async ({ event }) => {
    event.data.userId; /* typed as string */
  }
);

// Use event types when sending events:
await inngest.send(
  signupCompleted.create({
    userId: "user_123",
    email: "[email protected]",
    plan: "pro"
  })
);

环境变量设置

在 .env 文件或部署环境中设置以下环境变量：

# Required for production
INNGEST_EVENT_KEY=your-event-key-here
INNGEST_SIGNING_KEY=your-signing-key-here

# Force dev mode during local development
INNGEST_DEV=1

# Optional - custom dev server URL (default: http://localhost:8288)
INNGEST_BASE_URL=http://localhost:8288

⚠️ 常见陷阱：切勿在源代码中硬编码密钥。始终通过环境变量设置 INNGEST_EVENT_KEY 和 INNGEST_SIGNING_KEY。

重要：为本地开发启用 Dev 模式

创建 serve 端点或连接工作进程之前，请确保已启用 Dev 模式。 否则，Inngest 会默认使用 Cloud 模式，导致端点返回 500 错误。

将以下内容添加到 .env 文件（或 package.json 中的开发脚本）：

INNGEST_DEV=1

或添加到 package.json 脚本中：

{
  "scripts": {
    "dev": "INNGEST_DEV=1 tsx --watch src/server.ts"
  }
}

未设置 INNGEST_DEV 时的症状：

• GET /api/inngest 返回 {"code":"internal_server_error"}
• 服务端日志显示："In cloud mode but no signing key found"
• 开发服务器无法与应用同步

第 3 步：选择连接模式

Inngest 支持两种连接模式：

模式 A：Serve 端点（HTTP）

最适合无服务器平台（Vercel、Lambda 等）和现有 API。

模式 B：Connect（WebSocket）

最适合容器运行时（Kubernetes、Docker）和长时间运行的进程。

第 4A 步：提供端点（HTTP 模式）

创建一个 API 端点，向 Inngest 暴露你的函数：

// For Next.js App Router: src/app/api/inngest/route.ts
import { serve } from "inngest/next";
import { inngest } from "../../../inngest/client";
import { myFunction } from "../../../inngest/functions";

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [myFunction]
});

// For Next.js Pages Router: pages/api/inngest.ts
import { serve } from "inngest/next";
import { inngest } from "../../inngest/client";
import { myFunction } from "../../inngest/functions";

export default serve({
  client: inngest,
  functions: [myFunction]
});

// For Express.js
import express from "express";
import { serve } from "inngest/express";
import { inngest } from "./inngest/client";
import { myFunction } from "./inngest/functions";

const app = express();
app.use(express.json({ limit: "10mb" })); // Required for Inngest, increase limit for larger function state

app.use(
  "/api/inngest",
  serve({
    client: inngest,
    functions: [myFunction]
  })
);

🔧 框架特定说明：

• Express：必须使用 express.json({ limit: "10mb" }) 中间件，以支持更大的函数状态。
• Fastify：使用 inngest/fastify 中的 fastifyPlugin
• Cloudflare Workers：使用 inngest/cloudflare
• AWS Lambda：使用 inngest/lambda
• 对于其他框架，请查看此处的 serve 参考文档：https://www.inngest.com/docs-markdown/learn/serving-inngest-functions

⚠️ v4 变更： signingKey、signingKeyFallback 和 baseUrl 等选项现在通过 Inngest 客户端构造函数配置，而不是在 serve() 中配置。serve() 函数仅接受 client、functions 和 streaming。

⚠️ 常见陷阱：始终将 /api/inngest 用作端点路径，以启用自动发现。如果必须使用其他路径，则需要通过 -u 标志手动配置发现。

步骤 4B：以 Worker 身份连接（WebSocket 模式）

适用于需要维持持久连接的长时间运行应用：

// src/worker.ts
import { connect } from "inngest/connect";
import { inngest } from "./inngest/client";
import { myFunction } from "./inngest/functions";

(async () => {
  const connection = await connect({
    apps: [{ client: inngest, functions: [myFunction] }],
    instanceId: process.env.HOSTNAME, // Unique worker identifier
    maxWorkerConcurrency: 10 // Max concurrent steps
  });

  console.log("Worker connected:", connection.state);

  // Graceful shutdown handling
  await connection.closed;
  console.log("Worker shut down");
})();

连接模式的要求：

• 用于支持 WebSocket 的 Node.js 22.4+（或 Deno 1.4+、Bun 1.1+）
• 长时间运行的服务环境（非无服务器环境）
• 生产环境需要 INNGEST_SIGNING_KEY 和 INNGEST_EVENT_KEY
• 为生产环境的 Inngest 客户端设置 appVersion 参数，以支持滚动部署

v4 连接模式变更：

• 默认启用 Worker 线程隔离——WebSocket 连接会在 Worker 线程中执行，以防止事件循环饥饿。设置 isolateExecution: false 可使用单进程（或设置环境变量 INNGEST_CONNECT_ISOLATE_EXECUTION=false）
• rewriteGatewayEndpoint 回调已由 gatewayUrl 字符串选项取代（或使用环境变量 INNGEST_CONNECT_GATEWAY_URL）

步骤 5：使用 Apps 进行组织

随着系统不断扩展，可将函数组织到逻辑清晰的应用中：

// User service
const userService = new Inngest({ id: "user-service" });

// Payment service
const paymentService = new Inngest({ id: "payment-service" });

// Email service
const emailService = new Inngest({ id: "email-service" });

每个应用都会在 Inngest 控制面板中拥有独立的版块，并且可以独立部署。请使用描述性、以连字符分隔的 ID，使其与服务架构一致。

⚠️ 常见陷阱：更改应用的 id 会在 Inngest 中创建一个新应用。请确保各次部署使用的 ID 保持一致。

步骤 6：使用 inngest-cli 进行本地开发

启动 Inngest 开发服务器以进行本地开发：

# Auto-discover your app on common ports/endpoints
npx --ignore-scripts=false inngest-cli@latest dev

# Specify your app's URL manually
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest

# Custom port for dev server
npx --ignore-scripts=false inngest-cli@latest dev -p 9999

# Disable auto-discovery
npx --ignore-scripts=false inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest

# Multiple apps
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest -u http://localhost:4000/api/inngest

默认情况下，开发服务器可通过 http://localhost:8288 访问。

配置文件（可选）

对于复杂配置，可创建 inngest.json：

{
  "sdk-url": [
    "http://localhost:3000/api/inngest",
    "http://localhost:4000/api/inngest"
  ],
  "port": 8289,
  "no-discovery": true
}

特定环境的设置

本地开发

INNGEST_DEV=1
# No keys required in dev mode

生产环境

INNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_key

自定义开发服务器端口

INNGEST_DEV=1
INNGEST_BASE_URL=http://localhost:9999

如果应用运行在非标准端口（不是 3000），请使用 -u 标志指定 URL，确保开发服务器能够访问该应用。

常见问题与解决方案

端口冲突：如果端口 8288 已被占用，请指定其他端口：-p 9999

自动发现无法正常工作：请手动指定 URL：-u http://localhost:YOUR_PORT/api/inngest。如果使用 --no-discovery 标志，则必须使用 -u 标志——否则开发服务器将无法找到你的应用。

开发服务器中未显示函数：应用必须向开发服务器注册。当服务端点首次收到开发服务器的请求时，会自动完成注册。如果未能注册：(1) 确认已设置 INNGEST_DEV=1；(2) 确认开发服务器能够访问应用 URL；(3) 尝试在开发服务器运行时重启应用。

签名验证错误：确保生产环境中正确设置了 INNGEST_SIGNING_KEY

WebSocket 连接问题：确认连接模式使用的是 Node.js 22.4+

Docker 开发：在 Docker 中运行开发服务器时，应用 URL 请使用 host.docker.internal

后续步骤

1. 使用 inngest.createFunction() 创建第一个 Inngest 函数
2. 使用开发服务器上的“Invoke”按钮测试函数
3. 使用 inngest.send() 发送事件以触发函数
4. 设置正确的环境变量并部署到生产环境
5. 查看 inngest-middleware，了解如何添加日志记录、错误追踪及其他横切关注点
6. 在 Inngest 控制面板中监控函数

更改函数后，开发服务器会自动重新加载，让开发过程快速且迭代流畅。