使用 Inngest CLI 做本地开发/测试…

当需要安装或运行 Inngest CLI、启动 Dev Server、调试 serve 端点、本地发事件、Docker Compose、MCP 或自托管 `inngest start` 时使用。

适用场景

解决思路

1. 安装 CLI：优先使用 npx：`npx inngest-cli@latest dev`；也可用 yarn：`yarn dlx inngest-cli@latest dev`；pnpm：`pnpm dlx inngest-cli@latest dev`；全局安装：`npm install -g inngest-cli`；Docker 拉取：`docker pull inngest/inngest`。
2. 如果 npm 配置禁用 lifecycle scripts 且缺少 binary，重试 `npx --ignore-scripts=false inngest-cli@latest dev`；Bun 默认不支持 lifecycle scripts，因此即使 Bun 项目也优先用 `npx` 运行 CLI。
3. 启动本地 Dev Server：`npx inngest-cli@latest dev` 自动发现常见端口/端点上的 app，浏览器 UI 在 `http://localhost:8288`。
4. 指定 app URL：`npx inngest-cli@latest dev -u http://localhost:3000/api/inngest`；自定义端口：`npx inngest-cli@latest dev -p 9999`；多个 app：重复 `-u`，例如 `npx inngest-cli@latest dev -u http://localhost:3000/api/inngest -u http://localhost:4000/api/inngest`；禁用自动发现时配合 `-u`：`npx inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest`。
5. `inngest dev` 的标志：`--sdk-url`/`-u` 默认 `http://localhost:3000/api/inngest`，指定 app serve 端点 URL（可多个）；`--port`/`-p` 默认 `8288`，Dev Server 端口；`--host` 指定 Dev Server host；`--no-discovery` 默认 `false`，禁用 app 自动发现；`--no-poll` 默认 `false`，禁用轮询 app 变更；`--config` 指定配置文件路径；`--connect-gateway-port` 默认 `8289`，connect gateway 端点端口；`--persist` 默认 `false`，重启间持久化数据；`--poll-interval` 默认 `5`，app 轮询检查间隔秒数；`--queue-workers` 默认 `100`，执行器 worker 数；`--retry-interval` 默认 `0`，线性重试间隔秒数；`--tick` 默认 `150`，执行器队列轮询间隔毫秒。
6. 自动发现：不设置 `--no-discovery` 时，Dev Server 自动扫描常见开发端口（包括 3000、3030 等）和端点：`/api/inngest`、`/x/inngest`、`/.netlify/functions/inngest`、`/.redwood/functions/inngest`。
7. 配置文件：在项目根目录创建 `inngest.json`（或 `.yaml`、`.toml`），CLI 会向上遍历目录查找；JSON 示例包含 `sdk-url` 数组和 `no-discovery: true`；YAML 示例 `inngest.yaml` 包含 `sdk-url` 列表和 `no-discovery: true`。
8. 环境变量 `INNGEST_DEV`：`=1` 启用 Dev Mode（禁用签名验证），`=0` 强制 Cloud mode，也可接受 URL（如 `http://localhost:8288`）；未设置时默认 Cloud mode。
9. 环境变量 `INNGEST_BASE_URL`：设置 SDK 到 Inngest 通信的主机（如 `http://localhost:8288`）；大多数情况保持未设置。
10. 环境变量 `INNGEST_EVENT_KEY`：发送事件的身份验证 key；本地可用任意 dummy 值，Dev Server 不校验。
11. 环境变量 `INNGEST_SIGNING_KEY`：保护 Inngest 与 app 之间的请求；生产必需；决定哪个 Inngest 环境接收 sync。
12. 环境变量 `INNGEST_SIGNING_KEY_FALLBACK`：用于签名 key 轮换的 fallback key（v3.18.0+）。
13. 环境变量 `INNGEST_SERVE_ORIGIN`：Inngest 访问 app 的完整 origin URL（如 `https://my-app.com`）；通常从请求头自动推断；AWS Lambda、代理或隧道场景显式设置。
14. 环境变量 `INNGEST_SERVE_PATH`：serve 端点的 URL 路径（如 `/api/inngest`）；大多数情况自动推断。
15. 环境变量 `INNGEST_STREAMING`：启用响应流式传输（`true`/`false`）；在 Vercel 和 edge 运行时扩展超时限制。
16. 环境变量 `INNGEST_ENV`：目标 Inngest Environment；在某些平台自动检测。
17. 调试 serve 端点：运行 `curl -s http://localhost:3000/api/inngest | jq` 验证配置；正确响应为 `message: Inngest endpoint configured correctly.`、`hasEventKey`、`hasSigningKey`、`functionsFound`；如果 `functionsFound` 为 `0`，检查函数是否传入 `serve()` 调用。
18. 通过 SDK 本地发送事件：创建 `new Inngest({ id: "my-app" })`，然后 `await inngest.send({ name: "user/signup.completed", data: { userId: "user_123", email: "user@example.com" } })`。
19. 通过 curl 本地发送事件：`curl -X POST "http://localhost:8288/e/test" -H "Content-Type: application/json" -d '{"name": "user/signup.completed", "data": {"userId": "user_123", "email": "user@example.com"}}'`；URL 路径中的 event key（如 `test`）本地可任意。
20. 使用 `@inngest/test` 做单元测试：要求 `inngest@>=4.0.0`；安装 `npm install -D @inngest/test`；导入 `InngestTestEngine`。
21. `@inngest/test` 执行整个函数：`const t = new InngestTestEngine({ function: helloWorld }); const { result } = await t.execute(); expect(result).toEqual("Hello World!");`。
22. 测试单个 step：`const { result: stepResult } = await t.executeStep("calculate-price"); expect(stepResult).toEqual(123);`。
23. 断言 step 状态：`const { state } = await t.execute(); await expect(state["my-step"]).resolves.toEqual("output"); await expect(state["risky-step"]).rejects.toThrowError("failed");`。
24. Mock 事件：`const { result: eventResult } = await t.execute({ events: [{ name: "demo/event.sent", data: { message: "Hi!" } }] });`。
25. Mock step 响应：`const { result: mockResult } = await t.execute({ steps: [{ id: "external-api-call", handler() { return { status: "ok" }; } }] });`。
26. Mock sleep/waitForEvent：暂停型 step 需要 mock，例如 `await t.execute({ steps: [{ id: "wait-one-day", handler() {} }] });`。
27. 用测试框架标准 mocking（如 `jest.mock`、`vi.mock` 等）mock 外部依赖；`@inngest/test` 只处理 Inngest 特有的 mocking。
28. Docker 独立运行：`docker run -p 8288:8288 -p 8289:8289 inngest/inngest inngest dev -u http://host.docker.internal:3000/api/inngest`；用 `host.docker.internal` 访问宿主机 app；Docker Desktop 开箱即用；Linux 加 `--add-host=host.docker.internal:host-gateway` 或等价方法。
29. Docker Compose：app 服务设置 `INNGEST_DEV=1` 和 `INNGEST_BASE_URL=http://inngest:8288`，暴露 `3000:3000`；inngest 服务使用 `image: inngest/inngest`，`command: "inngest dev -u http://app:3000/api/inngest"`，暴露 `8288:8288` 和 `8289:8289`；端口 8288 是主服务器和 UI，8289 是 `connect()` WebSocket gateway；必须在 app 上设置 `INNGEST_DEV=1`，否则 TypeScript SDK 默认 Cloud mode 并跳过 Dev Server。
30. MCP Server：Dev Server 在 `http://127.0.0.1:8288/mcp` 暴露 MCP server（HTTP transport）；Claude Code 添加：`claude mcp add --transport http inngest-dev http://127.0.0.1:8288/mcp`；其他 MCP 客户端在 `.cursor/mcp.json` 等配置 `mcpServers` 的 `inngest-dev` 为 `http://127.0.0.1:8288/mcp`。
31. MCP 工具：`send_event` 发送事件触发函数；`list_functions` 列出注册函数和触发器；`invoke_function` 同步执行函数（默认 30s 超时）；`get_run_status` 获取函数运行详细状态；`poll_run_status` 轮询多个运行直到完成；`grep_docs` 按正则搜索 Inngest 文档；`read_doc` 读取指定文档页；`list_docs` 列出可用文档结构。
32. 自托管生产：运行 `inngest start --event-key <key> --signing-key <key>`；它与 `inngest dev` 不同，用于生产负载。
33. `inngest start` 标志：`--port`/`-p` 默认 `8288`；`--signing-key` 请求签名 hex key（偶数个字符）；`--event-key` app 身份验证 key（可重复）；`--sdk-url`/`-u` app serve URL（可重复）；`--redis-uri` 外部 Redis 连接；`--postgres-uri` 外部 PostgreSQL 连接；`--sqlite-dir` SQLite 数据库目录；`--poll-interval` 默认 `0`，app sync 轮询间隔秒数；`--queue-workers` 默认 `100`，执行器 worker 数；`--connect-gateway-port` 默认 `8289`，Connect gateway 端口；`--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 最大打开连接。
34. 全局标志：`inngest start` 还可使用 `--log-level`、`--verbose`、`--json`；环境变量遵循当前 CLI 和部署文档，不要假设每个 flag 都有 `INNGEST_` 环境变量等价物。
35. 默认持久化：内存 Redis + SQLite 位于 `./.inngest/main.db`；生产使用外部 Redis 和 PostgreSQL。
36. 部署工作流：本地用 `inngest dev` 开发，无需 keys；部署 app 到托管平台；用三种方式之一同步到 Inngest：CI/CD 中 `curl -X PUT https://your-app.com/api/inngest --fail-with-body`；Vercel/Netlify 集成在部署时自动同步；或通过 Inngest Cloud dashboard 手动 sync；生产设置 `INNGEST_EVENT_KEY` 和 `INNGEST_SIGNING_KEY`；从本地到生产无需代码改动，SDK 自动检测环境。
37. 平台注意事项 Express：需要 `express.json()` 中间件；默认 body limit 为 `100kb`，需增大以处理 Inngest payload（最大 4MB）。
38. 平台注意事项 AWS Lambda：显式设置 `INNGEST_SERVE_ORIGIN` 和 `INNGEST_SERVE_PATH`，自动推断会失败。
39. 平台注意事项 Firebase Cloud Functions：必须设置 `INNGEST_SERVE_PATH` 环境变量。
40. 平台注意事项 DigitalOcean Functions：在 `serve()` 配置中必须同时设置 `serveOrigin` 和 `servePath`。
41. 平台注意事项 Cloudflare Workers（Wrangler `--remote`）：连接 Dev Server 需要隧道（ngrok/localtunnel）。
42. 平台注意事项 Supabase Edge Functions：`servePath` 必须匹配函数名，因为 Supabase 会重写请求路径。
43. 平台注意事项 Google Cloud Run（1st gen）：不受官方支持；可能导致签名验证错误。
44. 平台注意事项 Docker：必须设置 `INNGEST_DEV=1`；SDK 默认 Cloud mode。
45. 平台注意事项外部 webhooks（Stripe、Clerk）：本地测试需要隧道方案（ngrok、localtunnel）。
46. 快速参考：`npx inngest-cli@latest dev` 自动发现启动 Dev Server；`npx inngest-cli@latest dev -u http://localhost:3000/api/inngest` 显式 app URL；`curl -s http://localhost:3000/api/inngest | jq` 检查 serve 端点健康；`curl -X POST http://localhost:8288/e/test -d '{"name": "test/event", "data": {}}'` 发送测试事件；部署后 CI/CD 同步 `curl -X PUT https://your-app.com/api/inngest --fail-with-body`；自托管生产 `inngest start --event-key <key> --signing-key <key>`。
47. 故障排查：Dev Server 找不到函数时，先启动 app；用 `-u` 指定正确 URL。
48. 故障排查：调试输出 `functionsFound: 0` 时，验证所有函数都在传给 `serve()` 的数组中。
49. 故障排查：SDK 连接 Cloud 而非 Dev Server 时，设置 `INNGEST_DEV=1`。
50. 故障排查：函数 sync 到错误的 Inngest 环境时，检查 `INNGEST_SIGNING_KEY` 是否匹配目标环境。
51. 故障排查：Inngest dashboard 出现重复 app 时，保持 `new Inngest({ id })` 中的 `id` 在部署间稳定。
52. 故障排查：webhook 事件未到达 Dev Server 时，为外部 webhook 源使用 ngrok 或 localtunnel。
53. 故障排查：dashboard 出现 `Unattached sync` 时，检查集成日志并手动 resync。
54. 相关：SDK 安装参考 `inngest-setup`；函数配置参考 `inngest-durable-functions`。

适用边界 · 注意事项

• 需要 Python 或 Go 的语言特定指导时，参考 Inngest 文档，而不是本技能。
• 需要通过 `inngest api` 检查 run/trace 时，使用 `inngest-api-cli`（如果可用）。
• Google Cloud Run（1st gen）不受官方支持，可能出现签名验证错误；不要假设其可用。