trigger-setup

开始使用 Trigger.dev

在现有项目中设置 Trigger.dev。完成后，SDK 已安装，trigger.config.ts 指向项目引用，/trigger 目录中至少有一个已导出的任务，并且 trigger dev 正在运行，因此任务会显示在仪表板中。

最快的方式是使用 CLI 自带的向导，它会完成下面的所有操作步骤，还会提供安装 MCP 服务和这些 Agent 技能的选项：

npx trigger.dev@latest init

尽可能使用 init。如果 init 不适用（例如单体仓库、需要扩展现有配置，或处于非交互式环境），再执行下面的手动步骤。

身份验证需要由用户本人完成

CLI 可以启动账户创建流程，但必须由用户验证电子邮件并授权访问。在 Agent 会话中，请启动可恢复的登录流程，而不是让 CLI 一直等待：

npx trigger.dev@latest login --email [email protected] --name "Alex Smith" --no-browser --no-wait

将输出的 URL 提供给用户，并请他们完成登录和授权。用户确认后，恢复已保存的授权：

npx trigger.dev@latest login --no-browser

不要代替用户创建账户或批准 CLI 访问。完成身份验证后，trigger init 可以直接创建首个组织和项目，无需跳转到仪表板。可自托管实例可能会禁用组织创建；如果是这样，请先让用户在其仪表板中创建组织。

手动设置

1. 身份验证（由用户授权）

在交互式终端中：

npx trigger.dev@latest login

对于 Agent 或无头终端，请使用上文所述的可恢复流程。自托管时，请在两条命令中都添加 --api-url https://your-trigger-instance.com。

2. 安装软件包

@trigger.dev/sdk 是运行时依赖；@trigger.dev/build 是开发依赖。请将两者固定为与你运行的 trigger.dev CLI 相同的版本；如果版本不匹配，CLI 会在 dev/deploy 期间发出警告。

npm add @trigger.dev/sdk@latest
npm add --save-dev @trigger.dev/build@latest

3. 编写 trigger.config.ts

在项目根目录下创建该文件（JavaScript 项目则使用 trigger.config.mjs）。project 引用和 dirs 是仅有的必填字段。

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>", // e.g. "proj_abc123", from the dashboard
  dirs: ["./src/trigger"], // where your tasks live
  maxDuration: 3600,
  retries: {
    enabledInDev: false,
    default: { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000, maxTimeoutInMs: 10000, randomize: true },
  },
});

添加 runtime: "bun" 即可使用 Bun 运行时。构建扩展（prismaExtension、puppeteer、additionalFiles 等）来自 @trigger.dev/build，应放在 build.extensions 中。

4. 添加首个任务

创建与 dirs 对应的目录，并从中导出一个任务。每个任务都必须是具名导出，并且具有在项目中唯一的 id。

// src/trigger/example.ts
import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { name: string }) => {
    return { message: `Hello ${payload.name}!` };
  },
});

5. 配置 tsconfig 和 gitignore

将 trigger.config.ts 添加到 tsconfig.json 的 include 数组中，并将 .trigger 添加到 .gitignore（CLI 会在其中写入本地开发状态）。

// tsconfig.json
{ "include": ["trigger.config.ts" /* ...existing */] }

# .gitignore
.trigger

6. 创建环境 API 密钥（由用户操作）

要从自己的代码触发任务，请在 Development 环境中创建一个仅具有 Trigger only 访问权限的命名 API 密钥，并将其设为 TRIGGER_SECRET_KEY。自托管用户还需设置 TRIGGER_API_URL。

# .env (or .env.local for Next.js)
TRIGGER_SECRET_KEY=tr_dev_sk_xxxxxxxx

7. 运行开发服务器

npx trigger.dev@latest dev

让它保持运行。任务会注册到仪表板，用户可以在任务的测试页面中触发测试运行。首次运行时，CLI 会提供安装 MCP 服务和 Agent 技能的选项；建议两者都安装。

从应用触发任务

创建任务后，请在后端代码中使用仅类型导入来触发任务，以免将任务代码打包到应用中。请按 ID 触发，而不要调用任务对象。

import { tasks } from "@trigger.dev/sdk";
import type { helloWorld } from "@/trigger/example"; // type-only

const handle = await tasks.trigger<typeof helloWorld>("hello-world", { name: "Ada" });

凡是运行此代码的环境都必须设置 TRIGGER_SECRET_KEY。框架相关的具体说明请参阅 Next.js / Remix / Node.js 指南。

单体仓库

支持两种布局：将任务放在共享软件包中（@repo/tasks，带有自己的 trigger.config.ts，并通过 workspace:* 使用），或直接在需要使用 Trigger.dev 的应用中安装 Trigger.dev。请从存放 trigger.config.ts 的目录运行 trigger dev。在搭建任一布局前，请参阅手动设置文档中的完整 Turborepo 示例。

常见错误

1. 在登录时阻塞 Agent 会话。 电子邮件验证和授权需要用户参与，但 CLI 授权本身可以恢复。

   • 错误做法：在 Agent 会话中启动 trigger login，并无限轮询。
   • 正确做法：运行 trigger login --email <email> --name <full-name> --no-browser --no-wait，将 URL 提供给用户，然后在用户批准后运行 trigger login --no-browser 继续。

2. CLI 和 SDK 版本不匹配。 trigger.dev CLI 与 @trigger.dev/sdk 的主版本不同会导致开发和部署失败。

   • 错误做法：使用旧版固定 SDK 运行 npx trigger.dev@latest dev。
   • 正确做法：保持 trigger.dev、@trigger.dev/sdk 和 @trigger.dev/build 的版本一致。

3. 从 @trigger.dev/sdk/v3 导入，或使用 client.defineJob()。 这两种方式都已过时。

   • 正确做法：始终从 @trigger.dev/sdk 导入；使用 task() 定义任务。

4. 任务未导出，或位于 dirs 目录之外。 配置目录中的任务必须是命名导出，否则不会被识别。

   • 正确做法：在 dirs 路径下的文件中使用 export const ... = task({ ... })。

5. 在后端代码中导入任务实例。 这会将任务打包进去。

   • 错误做法：在路由处理程序中使用 import { helloWorld } from "@/trigger/example"。
   • 正确做法：使用 import type { helloWorld }，再调用 tasks.trigger<typeof helloWorld>("hello-world", payload)。

6. 忘记设置 TRIGGER_SECRET_KEY。 缺少此项时，从应用触发任务会失败；CLI 登录后，dev 服务本身仍可正常运行。

参考资料

相关技能：

• trigger-tasks：完成设置后，用于编写任务本身，包括重试、等待、队列、计划任务、触发方式，以及完整的 trigger.config.ts。
• trigger-realtime：用于在前端显示实时运行状态。
• trigger-authoring-chat-agent 和 trigger-chat-agent-advanced：用于构建 AI 聊天 Agent。

文档：

• 快速入门
• 手动设置
• 配置文件

版本

此内容针对 @trigger.dev/sdk 4.7.4 生成。升级后请重新运行 trigger.dev 技能安装程序。