triggerdotdev/trigger.dev · 上手攻略

仓库：triggerdotdev/trigger.dev
链接：https://github.com/triggerdotdev/trigger.dev
分类：AI Agent 编排 · 后端工作流 · TypeScript
作者：Jay
更新：2026-08-30

这是什么

Trigger.dev 是一个用 TypeScript/JavaScript 构建和部署 AI Agent 与工作流的开源平台。它让你在现有代码库里写任务（tasks），然后一键部署到 Trigger.dev 托管基础设施，获得无超时、持久化、带重试和队列的长期运行任务，同时自带完整的链路追踪、日志和可观测性。

核心定位：解决"大模型 Agent 需要跑很长时间但 Lambda/Vercel 有 15 分钟超时"的问题。

解决什么问题

时间限制：AWS Lambda/Vercel Functions 等 Serverless 平台有超时上限，无法支撑长时间运行的 AI 任务（如爬取、分析、生成报告）
可靠性：网络抖动、API 报错时任务直接失败，没有自动重试和断点续跑
可观测性差：Agent 跑到哪一步、哪一步卡住、Token 消耗多少，开发者几乎是盲跑
基础设施负担：自己搭队列、Redis、worker、监控，成本高且维护复杂

Trigger.dev 的解法是：任务代码留在你的代码库里，用 SDK 定义，用 CLI 部署，剩下的（扩缩容、队列、重试、checkpoint）全部平台兜底。

快速安装

前提

Node.js 18+
npm / pnpm / yarn
Trigger.dev 账号（免费注册：https://cloud.trigger.dev）

初始化项目

# 在现有项目中初始化
npx trigger.dev@latest init

# 或 pnpm
pnpm dlx trigger.dev@latest init

init 会做以下事情： 1. 安装 @trigger.dev/sdk 和相关包 2. 创建 /trigger 目录，内含示例任务 3. 生成 trigger.config.ts 配置文件 4. 提示登录 CLI 并选择项目

安装 MCP 服务器（可选但推荐）

AI 编码助手（Claude Code / Cursor / Copilot）可用 MCP 服务器直接访问 Trigger.dev 文档、触发任务、部署项目：

npx trigger.dev@latest install-mcp

启动开发服务器

npx trigger.dev@latest dev

dev 命令会监听 /trigger 目录变动，自动注册任务到平台，并在本地运行任务，同时输出一个 Dashboard URL。

核心用法

定义一个任务（Hello World）

// /trigger/hello-world.ts
import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { message: string }) => {
    // 这里可以写任意长时间运行的代码，没有超时
    console.log(payload.message);
    return { success: true, message: payload.message };
  },
});

触发任务（从后端代码）

import { helloWorld } from "./trigger/hello-world";

// 触发一次运行
const handle = await helloWorld.trigger({ message: "Hello from my app!" });

// handle.id 可用于查询状态、取消、触发重试
console.log("Task running with ID:", handle.id);

⚠️ 从后端代码触发时，使用类型导入（import type）避免把任务代码打包进主应用。

重试配置

任务默认自动重试 3 次。也可以手动配置：

export const robustTask = task({
  id: "robust-task",
  retry: {
    maxAttempts: 10,         // 最多尝试 10 次
    factor: 1.8,             // 指数退避：500ms → 900ms → 1620ms …
    minTimeoutInMs: 500,
    maxTimeoutInMs: 30_000,
    randomize: false,
  },
  run: async (payload: any) => {
    // ...
  },
});

队列并发控制

export const oneAtATime = task({
  id: "one-at-a-time",
  queue: {
    concurrencyLimit: 1,  // 全局同时只有 1 个运行
  },
  run: async (payload: any) => {
    // ...
  },
});

定时任务（Cron）

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

export const dailyReport = scheduledTask({
  id: "daily-report",
  cron: "0 9 * * *",  // 每天 UTC 9:00 运行
  run: async (payload) => {
    // 生成并发送每日报告
  },
});

人类审批节点（Human-in-the-loop）

export const approvalTask = task({
  id: "approval-task",
  run: async (payload: { userId: string; amount: number }) => {
    // 先执行一些处理
    const result = await processPayment(payload);

    // 暂停，等人类审批
    const approval = await ctx.waitForInteraction({
      type: "approval",
      payload: { message: `确认支付 $${payload.amount}?` },
    });

    if (approval.approved) {
      await confirmPayment(result);
    }
  },
});

典型适用场景

AI Agent 后端编排：RAG 检索 → LLM 生成 → 写回数据库，整条链无需担心超时
长时数据处理：大规模爬虫、PDF 解析、视频转码，不受 Lambda 15 分钟限制
定时 AI 任务：每日自动生成报告、总结、发送邮件
多步骤工作流：需要人类在关键节点审批的审批流（金融、合规等）
实时流响应：配合 Realtime API 把 AI 生成过程流式推送到前端

坑与注意

不要用 client.defineJob()：那是 v2 已废弃 API，必须用 task() 或 scheduledTask()。
生产环境必须设置 TRIGGER_SECRET_KEY：在 .env（或 Next.js 的 .env.local）中配置，可在 Dashboard → API Keys 页面生成。
self-host 有一定复杂度：需要 Docker Compose 或 Kubernetes，适合有 DevOps 能力的团队；相比直接用 Cloud 版本，自托管需要自己维护 PostgreSQL 和 Redis。
冷启动延迟：Cloud 版本任务冷启动有轻微延迟，适合对延迟不极端敏感的场景（如后台任务、异步处理）。
付费层级限制：免费版有任务运行次数限制；重度使用需付费计划，详见 https://trigger.dev/pricing。
Trigger.dev MCP 服务器需要单独安装：默认不安装，init 时手动选择才会装。

与同类对比

平台	语言	超时限制	内置重试	追踪/日志	人类审批	自托管
Trigger.dev	TypeScript/JS	❌ 无	✅ 自动	✅ 完整链路	✅ waitForInteraction	✅ Docker/K8s
AWS Lambda	任意	✅ 15 分钟	⚠️ DIY (DLQ)	⚠️ CloudWatch	❌	❌
Vercel Functions	JS/TS	✅ 60s (付费 300s)	❌	⚠️	❌	❌
Inngest	TypeScript	❌ 无	✅	✅	❌	✅
Temporal	Go/Java	❌ 无	✅	✅	❌	✅
LangGraph (self-hosted)	Python	❌ 无	DIY	DIY	DIY	✅

Trigger.dev 核心差异：TypeScript 原生 + 最完善的 AI Agent 专属功能（Human-in-the-loop、Realtime streaming、MCP 集成），上手成本比 Temporal 低很多，专注在 AI Agent 场景而非通用工作流。

一句话推荐结论

如果你在用 TypeScript 构建 AI Agent、需要一个比 Lambda 更持久、比 Temporal 更轻量的方案，Trigger.dev Cloud 是目前上手最快、Agent 特性最完整的选项；如果你有强合规要求必须自托管，它也提供了完整的 Docker Compose 方案。

最小可跑命令清单

# 环境：Node.js 18+, npm/pnpm/yarn
# 账号：https://cloud.trigger.dev（免费注册）
# 步骤：
npm create next-app@latest my-agent-app --ts
cd my-agent-app
npx trigger.dev@latest init          # 选 y 安装 MCP server
# → 自动生成 /trigger/example.ts + trigger.config.ts
npx trigger.dev@latest dev             # 启动 dev server
# 打开 Dashboard URL，找到 Example Task，点 Test 按钮即可跑第一个任务

来源

仓库：https://github.com/triggerdotdev/trigger.dev
官方文档（Quick Start）：https://trigger.dev/docs/quick-start
任务文档：https://trigger.dev/docs/tasks/overview
Self-host 指南：https://trigger.dev/docs/self-hosting/overview
MCP 集成：https://trigger.dev/docs/mcp-introduction
官方 Discord：https://trigger.dev/discord