inngest-cli

Inngest CLI

掌握 Inngest CLI，用于本地开发、测试和可自托管的生产环境。CLI 提供 Dev Server，这是 Inngest Platform 功能完备的开源本地版本。

这些技能专注于 TypeScript。 如需 Python 或 Go 的指南，请参阅 Inngest 文档中的语言专属指南。核心概念适用于所有语言。

使用此技能进行 CLI 设置、Dev Server 工作流、本地测试、Docker、MCP 和自托管服务操作。如需通过 inngest api 检查运行记录/跟踪信息，请在可用时使用 inngest-api-cli。

安装

# npx (recommended — always latest)
npx inngest-cli@latest dev

# yarn
yarn dlx inngest-cli@latest dev

# pnpm
pnpm dlx inngest-cli@latest dev

# Global install
npm install -g inngest-cli

# Docker
docker pull inngest/inngest

如果你的 npm 配置禁用了生命周期脚本，且缺少二进制文件，请使用 npx --ignore-scripts=false inngest-cli@latest dev 重试。Bun 默认不支持生命周期脚本，因此即使在 Bun 项目中，也建议使用 npx 运行 CLI。

inngest dev — 本地 Dev Server

启动 Inngest 的内存中本地版本，并在 http://localhost:8288 提供浏览器界面。

# Auto-discover apps on common ports/endpoints
npx inngest-cli@latest dev

# Specify your app URL
npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

# Custom port
npx inngest-cli@latest dev -p 9999

# Multiple apps
npx inngest-cli@latest dev \
  -u http://localhost:3000/api/inngest \
  -u http://localhost:4000/api/inngest

# Disable auto-discovery (use with -u)
npx inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest

CLI 标志

标志	简写	默认值	描述
--sdk-url	-u	http://localhost:3000/api/inngest	应用服务端点 URL
--port	-p	8288	Dev Server 端口
--host			Dev Server 主机
--no-discovery		false	禁用应用自动发现
--no-poll		false	禁止轮询应用以检查变更
--config			配置文件路径
--connect-gateway-port		8289	Connect 网关端点端口
--persist		false	在重启之间保留数据
--poll-interval		5	应用轮询检查间隔（秒）
--queue-workers		100	执行器工作线程数
--retry-interval		0	线性重试间隔（秒）
--tick		150	执行器队列轮询间隔（毫秒）

自动发现

如果未指定 --no-discovery，Dev Server 会自动扫描常见端口和端点：

扫描的端口： 常见开发端口，包括 3000、3030 等

扫描的端点：

• /api/inngest
• /x/inngest
• /.netlify/functions/inngest
• /.redwood/functions/inngest

配置文件

在项目根目录中创建 inngest.json（或 .yaml、.toml）。CLI 会逐级向上遍历目录以查找该文件。

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

# inngest.yaml
sdk-url:
  - "http://localhost:3000/api/inngest"
  - "http://localhost:3030/api/inngest"
no-discovery: true

环境变量

变量	描述
INNGEST_DEV	=1 启用 Dev Mode（禁用签名验证）。=0 强制使用 Cloud 模式。也可接受 URL（例如 http://localhost:8288）。未设置时默认为 Cloud 模式。
INNGEST_BASE_URL	SDK 与 Inngest 通信使用的主机（例如 http://localhost:8288）。大多数情况下保持未设置。
INNGEST_EVENT_KEY	用于发送事件的身份验证密钥。本地可使用任意虚拟值——Dev Server 不会验证此值。
INNGEST_SIGNING_KEY	保护 Inngest 与应用之间的请求。**生产环境中必需。**决定同步内容发送到哪个 Inngest 环境。
INNGEST_SIGNING_KEY_FALLBACK	用于签名密钥轮换的备用密钥（v3.18.0+）。
INNGEST_SERVE_ORIGIN	Inngest 用于访问应用的完整源 URL（例如 https://my-app.com）。会根据请求标头自动推断；AWS Lambda、代理或隧道场景下请显式设置。
INNGEST_SERVE_PATH	serve 端点的 URL 路径（例如 /api/inngest）。大多数情况下会自动推断。
INNGEST_STREAMING	启用响应流式传输（true/false）。扩展 Vercel 和边缘运行时的超时限制。
INNGEST_ENV	目标 Inngest Environment。某些平台会自动检测。

调试 Serve 端点

验证你的 serve() 端点配置是否正确：

curl -s http://localhost:3000/api/inngest | jq

{
  "message": "Inngest endpoint configured correctly.",
  "hasEventKey": false,
  "hasSigningKey": false,
  "functionsFound": 3
}

如果 functionsFound 为 0，请检查是否已将函数传入 serve() 调用。

在本地测试函数

通过 SDK 发送事件

import { Inngest } from "inngest";

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

await inngest.send({
  name: "user/signup.completed",
  data: {
    userId: "user_123",
    email: "[email protected]",
  },
});

通过 curl 发送事件

curl -X POST "http://localhost:8288/e/test" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user/signup.completed",
    "data": {
      "userId": "user_123",
      "email": "[email protected]"
    }
  }'

URL 路径中的事件密钥（上例中的 test）在本地可以是任意值。

使用 @inngest/test 进行单元测试

需要 inngest@>=4.0.0。

npm install -D @inngest/test

import { InngestTestEngine } from "@inngest/test";
import { helloWorld } from "./functions";

// Execute full function
const t = new InngestTestEngine({ function: helloWorld });
const { result } = await t.execute();
expect(result).toEqual("Hello World!");

// Test a single step
const { result: stepResult } = await t.executeStep("calculate-price");
expect(stepResult).toEqual(123);

// Assert step state
const { state } = await t.execute();
await expect(state["my-step"]).resolves.toEqual("output");
await expect(state["risky-step"]).rejects.toThrowError("failed");

// Mock events
const { result: eventResult } = await t.execute({
  events: [{ name: "demo/event.sent", data: { message: "Hi!" } }],
});

// Mock step responses
const { result: mockResult } = await t.execute({
  steps: [{ id: "external-api-call", handler() { return { status: "ok" }; } }],
});

// Mock sleep/waitForEvent (pause-inducing steps require mocking)
await t.execute({
  steps: [{ id: "wait-one-day", handler() {} }],
});

使用测试框架的标准模拟功能（jest.mock、vi.mock 等）模拟外部依赖——@inngest/test 仅处理 Inngest 专属的模拟。

Docker 设置

独立运行

docker run -p 8288:8288 -p 8289:8289 \
  inngest/inngest \
  inngest dev -u http://host.docker.internal:3000/api/inngest

使用 host.docker.internal 访问运行在主机上的应用（在 Docker Desktop 上开箱即用）。在 Linux 上，添加 --add-host=host.docker.internal:host-gateway，或使用等效的主机访问方式。

Docker Compose

services:
  app:
    build: ./app
    environment:
      - INNGEST_DEV=1
      - INNGEST_BASE_URL=http://inngest:8288
    ports:
      - "3000:3000"
  inngest:
    image: inngest/inngest
    command: "inngest dev -u http://app:3000/api/inngest"
    ports:
      - "8288:8288"
      - "8289:8289"

端口 8288 是主服务和 UI。端口 8289 是 connect() WebSocket 网关。

**重要：**在应用上设置 INNGEST_DEV=1——TypeScript SDK 默认使用 Cloud 模式，这会跳过 Dev Server。

MCP 服务（AI 开发工具）

这些插件捆绑了 inngest-cloud，用于通过 OAuth 访问已部署的资源。 本地 Dev Server MCP 是一个单独的可选连接，名称为 inngest-dev。 两者可以在同一个编码会话中使用。如需本地 MCP 设置或连接 故障排查，请阅读本地 MCP 设置。

对于 Dev Server 上的应用和运行，请使用已配置的本地连接 （默认为 inngest-dev；保留现有连接的名称）。对于已部署的资源，使用 inngest-cloud，并选择目标账户和环境。如果目标不明确，请先确认， 再调用任一服务。切勿因为本地服务离线而从本地切换到 Cloud。

阅读每个服务的实时工具架构。本地工具包括应用、函数、事件、 运行和跟踪操作，以及内嵌的文档搜索。可用工具和输入取决于 正在运行的 Dev Server 版本。

inngest start — 可自托管的生产环境

以可自托管的生产服务模式运行 Inngest。这与 inngest dev 不同——此命令用于生产工作负载。

inngest start --event-key <key> --signing-key <key>

标志	短标志	默认值	描述
--port	-p	8288	服务端口
--signing-key			用于请求签名的十六进制密钥（字符数必须为偶数）
--event-key			应用的身份验证密钥（可重复指定）
--sdk-url	-u		应用服务 URL（可重复指定）
--redis-uri			外部 Redis 连接
--postgres-uri			外部 PostgreSQL 连接
--sqlite-dir			SQLite 数据库目录
--poll-interval		0	应用同步轮询间隔（秒）
--queue-workers		100	执行器工作线程数
--connect-gateway-port		8289	Connect 网关端口
--retry-interval		0	线性重试间隔（秒）
--tick		150	执行器队列轮询间隔（毫秒）
--no-ui			禁用 Web UI 和 GraphQL API
--postgres-conn-max-idle-time		5	PostgreSQL 空闲连接生命周期（分钟）
--postgres-conn-max-lifetime		30	PostgreSQL 连接最大复用时间（分钟）
--postgres-max-idle-conns		10	PostgreSQL 最大空闲连接数
--postgres-max-open-conns		100	PostgreSQL 最大打开连接数

还可使用 --log-level、--verbose 和 --json 等全局标志。对于环境变量，请参阅当前 CLI 和部署文档；不要假设每个标志都有对应的 INNGEST_ 环境变量。

默认持久化方式：内存中的 Redis + 位于 ./.inngest/main.db 的 SQLite。生产环境请使用外部 Redis 和 PostgreSQL。

部署工作流

从本地开发到生产环境

1. 在本地开发，使用 inngest dev——无需密钥，也无需为生产环境修改代码
2. 将应用部署到托管平台
3. 与 Inngest 同步，使用以下三种方法之一：

# Option 1: Curl from CI/CD
curl -X PUT https://your-app.com/api/inngest --fail-with-body

# Option 2: Vercel/Netlify integrations (automatic on deploy)

# Option 3: Manual sync via Inngest Cloud dashboard

4. 在生产环境中设置环境变量：

INNGEST_EVENT_KEY=<your-event-key>
INNGEST_SIGNING_KEY=<your-signing-key>

从本地开发迁移到生产环境时无需修改代码。SDK 会自动检测环境。

特定平台注意事项

平台	注意事项
Express	需要 express.json() 中间件；默认请求体大小限制为 100kb，需要增大以处理 Inngest 负载（最高 4MB）
AWS Lambda	必须显式设置 INNGEST_SERVE_ORIGIN 和 INNGEST_SERVE_PATH——自动推断会失败
Firebase Cloud Functions	必须设置 INNGEST_SERVE_PATH 环境变量
DigitalOcean Functions	serve() 配置中必须同时设置 serveOrigin 和 servePath
Cloudflare Workers (Wrangler --remote)	需要使用隧道（ngrok/localtunnel）连接 Dev Server
Supabase Edge Functions	servePath 必须与函数名称一致——Supabase 会重写请求路径
Google Cloud Run (1st gen)	不受官方支持；可能导致签名验证错误
Docker	必须设置 INNGEST_DEV=1——SDK 默认使用 Cloud 模式
外部 Webhook（Stripe、Clerk）	本地测试需要使用隧道解决方案（ngrok、localtunnel）

快速参考

# Start dev server with auto-discovery
npx inngest-cli@latest dev

# Start with explicit app URL
npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

# Check serve endpoint health
curl -s http://localhost:3000/api/inngest | jq

# Send test event via curl
curl -X POST http://localhost:8288/e/test -d '{"name": "test/event", "data": {}}'

# Sync after deploy (CI/CD)
curl -X PUT https://your-app.com/api/inngest --fail-with-body

# Self-hosted production
inngest start --event-key <key> --signing-key <key>

故障排除

问题	原因	解决方案
Dev Server 未找到函数	应用未运行或端口错误	先启动应用；使用 -u 指定正确的 URL
调试输出中显示 functionsFound: 0	未将函数传递给 serve()	确认传递给 serve() 的数组中包含所有函数
SDK 连接到 Cloud 而非 Dev Server	未设置 INNGEST_DEV	在环境中设置 INNGEST_DEV=1
函数同步到了错误的 Inngest 环境	签名密钥错误	检查 INNGEST_SIGNING_KEY 是否与目标环境匹配
Inngest 控制面板中出现重复应用	应用 id 已更改	在不同部署中保持 new Inngest({ id }) 中的 id 稳定不变
Webhook 事件未到达 Dev Server	未配置隧道	对于外部 Webhook 来源，请使用 ngrok 或 localtunnel
控制面板中显示“未关联同步”	自动同步静默失败	检查集成日志；手动重新同步

有关 SDK 安装，请参阅 inngest-setup；有关函数配置，请参阅 inngest-durable-functions。