Langfuse 的 Turborepo 任务执行详解turbo run 在 Monorepo 构建中的用法与实战【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuseturbo run是 Langfuse 这类 pnpm Turborepo 单体仓库中跨包执行任务的核心命令。本文以 Turborepo 官方技能文档中的cli/RULE.mdturbo run基础规则为主体结合当前仓库真实的 turbo.json、根 package.json 与各子包脚本讲清turbo run与turbo简写的边界、任务定义前提、参数透传、包过滤语法以及仓库内这些规则的实际落地方式。读完你应能读懂 Langfuse 的构建/测试/开发流水线是如何由根脚本委托给 Turborepo 编排的并能在自己的仓库中复刻同样的规范。基本用法完整形式与简写形式turbo run的主要作用是跨 monorepo 执行任务有两种等价写法# Full form (use in CI, package.json, scripts) turbo run tasks # Shorthand (only for one-off terminal invocations) turbo tasks两者的执行效果一致区别在于使用场景的约定完整形式turbo run tasks应写入一切会被提交、被 CI 执行的代码中简写形式turbo tasks仅用于人类或 Agent 在终端一次性敲出的临时命令。什么时候用turbo run什么时候用turbo规则文档给出的判定标准是“命令是否被写进代码”命令写进代码时一律使用turbo runpackage.jsonscriptsCI/CD 工作流GitHub Actions 等Shell 脚本文档任何静态化、会被提交的配置只在以下场景使用简写turbo直接在终端输入的一次性命令人或 Agent 的临时调用// package.json - ALWAYS use turbo run { scripts: { build: turbo run build, dev: turbo run dev, lint: turbo run lint, test: turbo run test } }# CI workflow - ALWAYS use turbo run - run: turbo run build --affected - run: turbo run test --affected# Terminal one-off - shorthand OK turbo build --filterwebLangfuse 仓库本身就是这条规则的标准示范。查看根 package.json所有跨包任务脚本全部采用完整形式委托给 Turborepo根包自身不承载任何任务逻辑build: turbo run build, build:check: turbo run build:check, typecheck: turbo run typecheck, start: turbo run start, dev: turbo run dev, lint: turbo run lint, test: turbo run test, db:generate: turbo run db:generate, db:migrate: turbo run db:migrate, db:seed: turbo run db:seed这保证了 Turborepo 的依赖图编排与缓存机制始终生效——如果根脚本绕过turbo run直接串联各包的构建命令并行化与增量缓存都会失效。运行任务任务必须先定义在 turbo.json文档强调任务必须在turbo.json中定义后才能运行。在 Langfuse 仓库中这一前提可以直接对照根目录 turbo.json 验证——其中tasks字段声明了全仓库可被turbo run调度的任务清单# Single task turbo build # Multiple tasks turbo run build lint test # See available tasks (run without arguments) turbo run当前仓库定义的典型任务包括任务关键配置说明builddependsOn: [db:generate, ^build]outputs: [dist/**, .next/**, !.next/cache/**]cache: true先跑 Prisma 客户端生成再构建本包的依赖包产物进缓存dev/dev:worker/dev:webcache: falsepersistent: truedependsOn: [db:generate]长驻开发服务不缓存testdependsOn: [^test, db:generate]cache: true测试依赖先于本包执行lintdependsOn: [repo/eslint-plugin#build, ^build]outputs: []先构建自研 ESLint 插件typecheckdependsOn: [db:generate, ^build]类型检查依赖生成的 Prisma 客户端db:migrate/db:deploy/db:reset/db:seed等cache: false数据库操作一律不缓存db:generatecache: falseinputs: [packages/shared/prisma/schema.prisma]Prisma 客户端写入node_modules属于副作用缓存命中只会回放日志、无法还原副作用故禁用缓存值得注意的细节是package#task形式的包级覆盖例如langfuse/shared#db:generate、repo/eslint-plugin#build、worker#dev它们用更具体的标识符对特定包的任务做差异化配置而不污染全局任务定义。任务定义在turbo.json而任务的实际命令则落在各子包的package.json中。比如build任务在 web/package.json 中对应next build在 worker/package.json 中对应tsctest在 web 中对应多 project 的vitest run在 worker 中对应vitest run。turbo run build时Turborepo 会依据依赖图决定执行顺序^build先构建被依赖的langfuse/shared等内部包并尽可能并行执行无依赖关系的包。通过--向底层脚本透传参数使用--可以把参数原样传递给包内脚本--之后的内容全部直达任务本身turbo run build -- --sourcemap turbo test -- --watch turbo lint -- --fix仓库中有一个真实案例根脚本dev:web-webpack就是这条规则的实践——dev:web: turbo run dev --filterweb, dev:web-webpack: turbo run dev --filterweb -- --webpack--webpack被透传给 web/package.json 的dev脚本next dev使 Next.js 以 webpack 模式启动。同理web 包的lint脚本内部通过--concurrency 2控制 ESLint 并发这些细节参数都由包内脚本自行声明turbo run只负责把调用分发到正确的包。包选择--filter 缩小执行范围默认情况下turbo run会在所有工作区包中执行任务用--filter别名-F可以收窄范围。Langfuse 的 pnpm-workspace.yaml 声明了工作区成员packages: - web - worker - packages/** - ee因此turbo run lint默认覆盖web、worker、packages/*与ee全部包。仓库中用 filter 的典型写法dev:worker: turbo run dev --filterworker, dev:web: turbo run dev --filterwebturbo build --filterweb turbo test --filter./apps/*按包名、目录、scope glob如--filterrepo/*、依赖/被依赖传播语法pkg...、...pkg以及否定语法!pkg的完整过滤体系参见同技能目录下的 filtering/RULE.md其中还包括 CI 最常用的--affected只跑相对默认分支有变更的包及其下游与--affected-base/--affected-head自定义对比基线。快速参考继承文档的 Quick Reference 表并结合本仓库的实际命令习惯GoalCommandBuild everythingturbo buildBuild one packageturbo build --filterwebMultiple tasksturbo build lint testPass args to scriptturbo build -- --argPreview runturbo build --dryForce rebuildturbo build --force只开发单个应用Langfuse 实际用法turbo run dev --filterweb查看可用任务turbo run--dry用于预览将执行的任务而不实际运行可用--dryjson获取机器可读输出--force则忽略所有缓存强制重跑——当怀疑缓存命中导致结果陈旧时例如turbo.json的build任务特意将NEXT_IGNORE_BUILD_ERRORS纳入env就是为了避免“未做类型检查的构建”与“做了类型检查的构建”共享同一缓存条目这是排查缓存问题的第一手段。延伸阅读仓库内的配套参考文档围绕turbo run的更细粒度内容仓库中随技能文档一并维护了成套参考资料均以仓库根目录相对路径给出cli/commands.mdturbo run完整 flag 参考--affected、--concurrency、--cache、--output-logs、--graph等以及turbo-ignore、turbo watch、turbo prune等其他命令filtering/RULE.md--filter与--affected的完整语法与 CI 模式configuration/tasks.md 与 configuration/RULE.mdturbo.json任务字段dependsOn、outputs、inputs、env、cache、persistent与包级配置详解SKILL.md整体技能入口包含“根脚本只委托、任务逻辑放包内”等关键约定与决策树。小结turbo run的使用规范可以浓缩为三条一写进代码package.jsonscripts、CI、shell 脚本、文档的命令一律用完整形式turbo run task简写仅留给终端一次性调用二任务必须先注册在turbo.json中且实际命令落在各子包脚本里由 Turborepo 负责依赖排序、并行与缓存三跨包调用默认全量用--filter收窄用--向包内脚本透传参数。Langfuse 仓库的根 package.json、turbo.json 与各子包脚本共同构成了一套可直接对照学习的真实样本。【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考