Trigger.dev 构建扩展（@trigger.dev/build）权威指南：从 Prisma 三模式到 Agent Skills 的完整演进

AI Agent后端任务调度开发工具可观测性AI 应用【免费下载链接】trigger.devTrigger.dev – build and deploy durable AI agents and workflows项目地址https://gitcode.com/gh_mirrors/tr/trigger.dev点击查看免费下载本篇技术指南以 Trigger.dev 开源仓库中 packages/build/CHANGELOG.md 为主体骨架系统梳理trigger.dev/build包从 3.0.0 到 4.6.3 的核心能力演进prismaExtension 三模式重构、syncEnvVars 环境变量同步体系、Playwright / Puppeteer / ffmpeg 等运行时依赖扩展以及 v4.5 引入的 Agent Skills。读者读完将掌握每个构建扩展的适用场景、完整配置方式与迁移路径并能结合源码理解其底层实现机制。trigger.dev/build是 Trigger.dev v3 起新增的官方构建包负责在trigger.dev deploy/trigger.dev dev构建与部署过程中注入构建层Build Layer。它把安装系统依赖、运行 prisma generate、同步云平台环境变量、复制额外文件等操作统一抽象为声明式的构建扩展Build Extension声明在项目根目录的trigger.config.ts中。本文所有示例与行为均以当前仓库源码为准。一、构建扩展的核心机制与触发时机1.1 扩展的生命周期挂钩trigger.dev/build本身不实现构建引擎而是复用trigger.dev/core/v3/build暴露的底层类型与工具。从 packages/build/src/extensions/index.ts 可以看到包重新导出了BuildContext、BuildExtension、BuildLayer、BuildLogger、BuildSpinner、RegisteredPlugin等核心类型以及binaryForRuntime、esbuildPlugin两个实用函数。扩展的核心是BuildExtension接口它提供多个生命周期挂钩hooks常见的有onBuildComplete(context, manifest)构建完成后回调syncEnvVars系列扩展正是在此阶段执行beforeBuild/afterBuild类挂钩用于安装系统包、生成 Prisma 客户端、复制文件等。以 syncEnvVars 源码 为例扩展在onBuildComplete中读取manifest.deploy.env、manifest.environment、manifest.branch调用用户回调拿到环境变量后通过context.addLayer({ id: sync-env-vars, deploy: { env, parentEnv, secretEnv, secretParentEnv, override } })把结果注入构建产物override默认值为true即同步上来的变量默认覆盖已有同名变量。1.2 一个关键约束dev 目标不执行同步在 syncEnvVars 实现 中第一行判断即为if (context.target dev) return;。这意味着syncEnvVars系列扩展只在部署deploy时生效本地trigger dev开发模式下不会拉取远端平台的环境变量这是构建扩展行为的重要边界。二、prismaExtension面向 Prisma 生态的三模式重构prismaExtension是trigger.dev/build中最重要的扩展之一。4.1.1 版本对它进行了完全重构引入了必须显式声明的mode参数破坏性变更旧配置不声明mode将无法工作以应对 Prisma 从 5.x 到 7 的架构变迁。类型定义见 packages/build/src/extensions/prisma.ts。2.1 Legacy Mode传统模式适用场景Prisma 6.x 及更早版本使用prisma-client-jsprovider。能力清单见 源码注释部署时自动执行prisma generate支持单文件 schemaprisma/schema.prisma与多文件 schemaPrisma 6.7schema 指向目录新增支持通过configFile加载prisma.config.ts基于官方prisma/config包自动提取 schema 与 migrations 路径migrate: true时执行prisma migrate deploy且要求配置directUrlEnvVarNametypedSql: true时为prisma generate追加--sql参数要求 Prisma 5.19 且 schema 声明previewFeatures [typedSql]clientGenerator指定多 generator 场景下只生成某一个例如跳过typegraphql-prismaversion手动覆盖自动检测的版本自动检测顺序为externals →prisma/client→prisma包。单文件 schema 配置generator client { provider prisma-client-js previewFeatures [typedSql] } datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DATABASE_URL_UNPOOLED) }// trigger.config.ts import { prismaExtension } from trigger.dev/build/extensions/prisma; extensions: [ prismaExtension({ mode: legacy, schema: prisma/schema.prisma, migrate: true, typedSql: true, directUrlEnvVarName: DATABASE_URL_UNPOOLED, }), ];多文件 schemaPrisma 6.7schema直接指向目录./prisma其余参数不变。Config File 方式Prisma 6使用configFile而非schema两者互斥要么指定其一不能同时指定// trigger.config.ts prismaExtension({ mode: legacy, configFile: ./prisma.config.ts, migrate: true, directUrlEnvVarName: DATABASE_URL_UNPOOLED, // 迁移所需 });// prisma.config.ts import { defineConfig, env } from prisma/config; import dotenv/config; export default defineConfig({ schema: prisma/schema.prisma, migrations: { path: prisma/migrations, }, datasource: { url: env(DATABASE_URL), directUrl: env(DATABASE_URL_UNPOOLED), }, });被自动提取的内容包括schemaschema 文件或目录路径与migrations.path迁移目录路径。官方测试过的版本Prisma 6.14.0、6.7.0多文件 schema、5.x。2.2 Engine-Only Mode引擎专用模式适用场景自定义 Prisma Client 输出路径希望自行掌控prisma generate的执行时机例如放在 prebuild 脚本中。行为见 源码注释只安装 Prisma 引擎二进制不做客户端生成自动从prisma/client检测版本带文件系统回退也支持version手动指定以获得可复现构建自动设置PRISMA_QUERY_ENGINE_LIBRARY与PRISMA_QUERY_ENGINE_SCHEMA_ENGINE环境变量指向正确的二进制目标路径binaryTarget可指定二进制平台默认debian-openssl-3.0.xTrigger.dev Cloud 目标本地 ARM Docker 可用linux-arm64-openssl-3.0.xsilent选项可抑制构建进度输出。schema 要求必须包含正确的 binaryTargets 以适配 Trigger.dev Cloudgenerator client { provider prisma-client-js output ../src/generated/prisma binaryTargets [native, debian-openssl-3.0.x] } datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DATABASE_URL_UNPOOLED) }扩展配置// 自动检测版本 prismaExtension({ mode: engine-only }); // 显式指定版本推荐保证构建可复现 prismaExtension({ mode: engine-only, version: 6.19.0 });package.json 配套脚本自行执行 generate{ scripts: { prebuild: prisma generate, dev: trigger dev, deploy: trigger deploy } }官方测试过的版本Prisma 6.19.0、6.16.0。2.3 Modern Mode现代模式适用场景Prisma 6.16 使用新prisma-clientproviderengineType client或为 Prisma 7 做准备。行为见 源码注释零配置自动将prisma/client标记为 external适用于纯 TypeScript 客户端无 Rust 二进制需要数据库适配器如 PostgreSQL 用prisma/adapter-pg与 Engine-Only 模式相同客户端生成由你自行管理。prismaExtension({ mode: modern });Prisma 6.16engineTypeschemagenerator client { provider prisma-client output ../src/generated/prisma engineType client previewFeatures [views] } datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DATABASE_URL_UNPOOLED) }Prisma 7 schemagenerator client { provider prisma-client output ../src/generated/prisma } datasource db { provider postgresql }官方测试过的版本Prisma 6.16.0engineType client、Prisma 6.20.0-integration-next.87 beta。2.4 版本兼容矩阵与迁移指南Prisma 版本推荐模式说明 5.0Legacy较老的 Prisma 版本5.0 – 6.15Legacy标准 Prisma 配置6.7Legacy支持多文件 schema6.16Engine-Only 或 ModernModern 模式要求engineType client6.207.0 betaModern新架构的 Prisma 7三条迁移路径旧版 prismaExtension → Legacy Mode只需补上mode: legacy// Old prismaExtension({ schema: prisma/schema.prisma, migrate: true }); // New prismaExtension({ mode: legacy, schema: prisma/schema.prisma, migrate: true });自行管理 Prisma 生成 → Engine-Only ModeprismaExtension({ mode: engine-only, version: 6.19.0 })version与你的prisma/client保持一致。备战 Prisma 7 → Modern Mode先把 schema 改为prisma-clientprovider再添加数据库适配器依赖最后配置prismaExtension({ mode: modern })。注除了mode变为必填外其余既有选项保持向后兼容新增的configFile不影响使用schema的既有配置。2.5 源码级补充版本自动检测机制Prisma 版本自动检测并非简单读取 package.json。从 prisma.ts 源码 可以看到检测流程使用 ESM 解析器mlly先解析prisma/client的模块入口再通过pkg-types的resolvePackageJSON向上回溯查找 package.json并带有一个过滤esm type marker的 test 函数prisma/client解析失败时才回退到prisma包。这套机制保证了在 pnpm / yarn / npm 不同安装布局下都能准确定位真实版本。三、环境变量同步syncEnvVars 扩展家族Trigger.dev 允许构建时从外部平台拉取环境变量注入部署镜像这一族扩展全部基于统一的syncEnvVars(fn, options)原语位于 packages/build/src/extensions/core/syncEnvVars.ts。3.1 核心原语与安全过滤syncEnvVars接受一个回调函数参数为{ projectRef, environment, branch, env }返回两种形态之一// 形态一纯键值对 { DATABASE_URL: postgres://... } // 形态二带元信息的数组 [ { name: DATABASE_URL, value: postgres://..., isSecret: true }, { name: STRIPE_KEY, value: sk_..., isParentEnv: true }, ]关键安全机制见 syncEnvVars.ts#L20-L69 与 L138-L155维护了一张UNSYNCABLE_ENV_VARS黑名单PWD、PATH、HOME、SHELL、GITHUB_TOKEN、NVM_*、BUN_INSTALL等约 40 个系统/会话变量同步时逐一剔除前缀黑名单UNSYNCABLE_ENV_VARS_PREFIXES [TRIGGER_]所有TRIGGER_开头的变量都会被剥离这是 3.0.3 引入的行为用于防止把 Trigger.dev 内部变量同步回去导致部署错误过滤后的结果通过addLayer的deploy.env/parentEnv/secretEnv/secretParentEnv四个通道注入部署镜像。3.2 将环境变量标记为 Secret4.5.4 起回调可以返回{ name, value, isSecret: true }该变量会以脱敏redacted形式存储在 Trigger.dev 控制台与手工创建的 secret 环境变量行为一致。这解决了此前通过syncEnvVars同步的敏感凭据在控制台明文可见的问题。3.3 针对云平台的专用扩展扩展版本引入作用syncVercelEnvVars({ projectId, teamId, accessToken })3.1.0 / 4.0.0同步 Vercel 项目环境变量3.2.0 增加teamId选项4.0.0 修复了同步到错误 preview 分支环境变量的缺陷4.2.0 起支持跳过 Vercel API、直接从env.process读取 Vercel 构建环境变量syncNeonEnvVars()4.2.0从 Neon 数据库项目同步环境变量自动检测分支并为非生产、非 dev 环境staging、preview构建合适的 PostgreSQL 连接串syncSupabaseEnvVars()4.4.3拉取 Supabase 数据库连接串并保存为 Trigger.dev 环境变量3.4 自定义回调示例可复制// trigger.config.ts import { syncEnvVars } from trigger.dev/build/extensions/core/syncEnvVars; export default { // ... extensions: [ syncEnvVars(async ({ env, projectRef, environment, branch }) { const secrets await fetchMySecrets(projectRef, environment, branch); return secrets.map((s) ({ name: s.name, value: s.value, isSecret: true, // 4.5.4脱敏存储 })); }), ], };四、运行时依赖扩展为部署镜像装配系统级依赖Trigger.dev 的构建产物是容器镜像运行 AI Agent / 浏览器自动化等任务往往需要额外的系统库与可执行文件。以下是 CHANGELOG 中出现的全部运行时扩展。4.1 Playwright 扩展4.0.0 引入4.6.0 修复playwright({ browsers?, headless?, version? })用于在部署镜像中安装 Playwright 浏览器及其全部系统依赖。从 playwright.ts 源码 可以看到browsers要安装的浏览器可选chromium | firefox | webkit默认[chromium]只选需要的浏览器可显著缩短构建时间、减小镜像体积headless是否以无头模式运行默认trueversionPlaywright 版本覆盖不传则自动检测。扩展内置了从 Playwright 官方 registry 整理出的 Debian 12 系统依赖清单含xvfb、fonts-noto-color-emoji、libgbm1、libnss3等见 playwright.ts#L30-L60构建时通过aptGet机制安装保证 Chromium 在容器内可启动。版本兼容性提醒Playwright 1.58 修改了playwright install --dry-run的输出格式导致下载浏览器阶段的部署镜像构建失败。4.6.0 已修复该问题请使用 Playwright 1.58 搭配trigger.dev/build4.6.0及以上版本。// trigger.config.ts import { playwright } from trigger.dev/build/extensions/playwright; extensions: [ playwright({ browsers: [chromium], headless: true, }), ];4.2 Puppeteer 扩展3.0.6 引入puppeteer()为部署镜像安装 Puppeteer 所需依赖并设置PUPPETEER_EXECUTABLE_PATH环境变量3.0.8确保 Puppeteer 能定位到已安装的 Chromium 可执行文件。4.3 ffmpeg 扩展3.0.0 引入4.0.0 支持 v7ffmpeg({ version })安装指定版本的 ffmpeg。3.0.0 随trigger.dev/build首发引入4.0.0 起支持ffmpeg({ version: 7 })覆盖 ffmpeg v7 新版本线。4.4 aptGet 扩展3.0.0 引入aptGet({ packages })是向镜像安装系统包的最通用方式Playwright、Puppeteer 等扩展底层也依赖它import { aptGet } from trigger.dev/build/extensions/core/aptGet; extensions: [ aptGet({ packages: [libpq-dev, curl] }), ];4.5 其他扩展lightpanda({})4.0.0 引入安装 Lightpanda——一个轻量级无头浏览器运行时适合在受限资源环境中执行网页任务audioWaveform(options)3.0.6 修复3.3.14 补齐构造选项安装 audiowaveform 工具用于音频波形渲染additionalPackages/additionalFilescore 目录下分别声明额外的 npm 包与需要复制进镜像的额外文件copyFiles内部逻辑位于 packages/build/src/internal/copyFiles.ts。五、Agent Skills为 chat.agent 打包技能4.5.05.1 核心用法4.5.0 为chat.agent引入了 Agent Skills 能力PR #3543。其核心设计是约定优于配置在你的任务代码旁放一个包含SKILL.md和辅助脚本/引用的文件夹用skills.define({ id, path })注册后CLI 会自动将其打进部署镜像——完全不需要改动trigger.config.ts。// task.ts import { skills } from trigger.dev/sdk/v3; import { chat } from trigger.dev/ai/chat; const pdfSkill skills.define({ id: pdf-extract, path: ./skills/pdf-extract, }); export const myAgent chat.agent({ // ... skills: [await pdfSkill.local()], });注册后Agent 的系统提示词中只会得到一行技能摘要完整的操作说明由 Agent 按需通过loadSkill发现避免把大段指令塞进上下文。bash与readFile两个工具按技能作用域隔离内置了路径穿越防护、输出上限与 abort-signal 传播等安全机制。该模式基于 AI SDK cookbook 的 agent-skills 模式构建因此可跨模型提供商移植。需要说明的是当前仅 SDK CLI 支持即技能文件在本地仓库控制台直接编辑 SKILL.md 文本仍在路线图中。5.2 相关 CLI 行为变更4.5.16 起trigger.dev deploy与trigger.dev dev会在以下场景给出警告并附带修复建议代码通过createRequire()加载了部署镜像中不可用的包此前这类问题只在生产运行时才暴露部署时不再丢弃你的代码产生的 bundler 警告而是直接展示。4.6.0 起Trigger.dev 默认使用 Zod 4 校验 schema同时继续支持 Zod 3.25.56 及之后的 3.x 版本Zod 仍是执行 schema 的包运行时依赖peer dependency 范围允许包管理器复用你项目里兼容的 Zod 3 或 Zod 4 安装。六、发布工程与包质量改进CHANGELOG 同时记录了若干影响安装与构建体验的工程化变更4.5.15停止在发布包中携带编译后的测试文件。此前*.test.ts会被编译进dist既给每次安装增加无谓体积又让 tar 包内残留require(vitest)的模块vitest 并非依赖会触发扫描包内每个文件的工具的误报。4.5.10为 TypeScript 7 兼容性刷新包构建同时保留既有运行时入口点。使用 TypeScript 7 且依赖emitDecoratorMetadata()的项目可额外安装可选的typescript/typescript6兼容包该包保持可选安装 Trigger.dev CLI 不会附带额外编译器。3.0.1修复了包版本不匹配的误报问题此前trigger.dev/core与trigger.dev/build版本不同步时会错误告警。3.0.0确保BuildManifest从trigger.dev/build正确导出修复emitDecoratorMetadata与带extends的 tsconfig 组合问题增加自定义 esbuild 插件支持。七、版本与依赖对照速查trigger.dev/build每个版本都与trigger.dev/core严格同版本发布例如 4.6.3 ↔ core 4.6.3升级时两者需保持一致。CHANGELOG 中的完整依赖链可参考 packages/build/package.json 与仓库根目录的 pnpm-workspace.yaml。需要特别留意的是v3 与 v4 之间的升级属于 Major 变更3.0.0 与 4.0.0 均标记为 Major Changes涉及 Run Engine 2.0alpha等底层架构变化升级前建议按官方 v4 升级指南核对配置。八、总结trigger.dev/build的发展脉络清晰地反映了 Trigger.dev 构建体系的三个方向生态适配prismaExtension 从单一模式重构为 Legacy / Engine-Only / Modern 三模式精确覆盖 Prisma 5.x → 7 的全部演进路径并引入prisma.config.ts支持与文件系统版本检测平台集成syncEnvVars 原语 Vercel / Neon / Supabase 专用扩展配合TRIGGER_前缀剥离与黑名单过滤形成安全可控的跨平台环境变量同步体系AI 原生能力Agent Skills 让技能打包进部署镜像成为约定而非配置Playwright / Puppeteer / ffmpeg / Lightpanda 等扩展则让浏览器自动化与媒体处理任务在云上开箱即用。如需继续深入推荐直接阅读 packages/build/src/extensions/prisma.ts、syncEnvVars.ts 与 playwright.ts 的完整实现以及配套测试 syncEnvVars.test.ts 与 playwright.test.ts。赞分享AI Agent后端任务调度开发工具可观测性AI 应用【免费下载链接】trigger.devTrigger.dev – build and deploy durable AI agents and workflows项目地址https://gitcode.com/gh_mirrors/tr/trigger.dev点击查看免费下载相关推荐在Trigger.dev项目中集成Prisma ORM的完整指南在Trigger.dev项目中集成Prisma ORM的完整指南 前言 在现代应用开发中ORM Object Relational Mapping 工具已经成AI Agent后端任务调度开发工具可观测性AI 应用Trigger.dev 项目从 v2 升级到 v3 的完整指南Trigger.dev 项目从 v2 升级到 v3 的完整指南 引言 还在为Trigger.dev v2中的超时限制、复杂的 io.runTask 包装和集成SAI Agent后端任务调度开发工具可观测性AI 应用Trigger.dev构建扩展真正的运行时自由Trigger.dev构建扩展真正的运行时自由 Trigger.dev的构建扩展系统是一个高度模块化和可扩展的架构允许开发者在构建过程中注入自定义逻辑实现AI Agent后端任务调度开发工具可观测性AI 应用上一篇Dolphin 能力拆解从 PDF 与文档图像到结构化 Markdown 的完整实战下一篇Cherry Studio 历史 AI 用量迁移AiUsageRecordMigrator 的实现原理与实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考