findscripter 何时使用
适用：
- 新建或改造 Turborepo 项目（apps/* + packages/* + 根 turbo.json）。
- 编写/调优构建流水线（dependsOn、outputs、inputs、cache、persistent）。
- 接入远程缓存（Vercel 托管或自建），让 CI 与本地共享产物。
- 用
--filter只构建受影响的包，加速 CI。 - 排查缓存未命中、缓存被错误命中或失效问题。
不该用（负边界）：
- 任务与 Turborepo 缓存无关，或使用 Nx/Bazel/Lerna 等其他工具。
- 仅需通用 CI 配置、与缓存键无关的纯业务改动。
- 缺少必要输入（仓库结构、包名、CI 平台、token）时，先澄清再动手，不要凭空假设。
步骤
- 厘清目标与约束：仓库结构、包管理器、CI 平台、是否需要远程缓存。
- 配置根
turbo.json流水线：声明任务依赖、缓存产物与输入。 - 如需跨包覆盖，用包级
turbo.json的extends: ["//"]。 - 接入远程缓存（Vercel 或自建），在 CI 注入
TURBO_TOKEN/TURBO_TEAM。 - 在 CI 用
--filter只构建变更包及其依赖关系。 - 校验：
--dry-run看任务图，--summarize看命中情况，确认缓存按预期命中/失效。
指令
流水线核心字段：
| 字段 | 含义 |
|---|---|
| dependsOn | 必须先完成的任务（^build 指上游包的 build） |
| outputs | 要缓存的产物文件 |
| inputs | 影响缓存键的输入文件 |
| cache | 是否缓存（dev/部署类设 false） |
| persistent | 长驻任务，如 dev server |
调试缓存：
turbo build --dry-run # 预演将要执行的任务
turbo build --summarize # 输出缓存命中摘要
turbo build --graph # 任务依赖图
turbo build --force # 强制忽略缓存
TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web
过滤与范围（CI 提速关键）：
turbo build --filter=@myorg/web # 单个包
turbo build --filter=@myorg/web... # 包 + 其依赖
turbo build --filter=...@myorg/ui # 包 + 依赖它的包
turbo build --filter='...[origin/main]' # 相对 main 的变更包
turbo build --filter='./apps/*' # 目录下的包
turbo build --filter='!@myorg/docs' # 排除某包
示例
根 turbo.json（保留源关键约束，如排除 .next/cache）：
{
"$schema": "https://turbo.build/schema.json",
"globalDependencies": [".env", ".env.local"],
"globalEnv": ["NODE_ENV", "VERCEL_URL"],
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"],
"env": ["API_URL", "NEXT_PUBLIC_*"]
},
"test": {
"dependsOn": ["build"],
"outputs": ["coverage/**"],
"inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
},
"lint": { "outputs": [], "cache": true },
"typecheck": { "dependsOn": ["^build"], "outputs": [] },
"dev": { "cache": false, "persistent": true },
"clean": { "cache": false }
}
}
包级覆盖（apps/web/turbo.json）：
{
"$schema": "https://turbo.build/schema.json",
"extends": ["//"],
"pipeline": {
"build": {
"outputs": [".next/**", "!.next/cache/**"],
"env": ["NEXT_PUBLIC_API_URL", "NEXT_PUBLIC_ANALYTICS_ID"]
}
}
}
Vercel 远程缓存接入：
npx turbo login
npx turbo link
turbo build --remote-only
# CI 注入：TURBO_TOKEN=... TURBO_TEAM=...
GitHub Actions CI（只构建变更包）：
name: CI
on:
push: { branches: [main] }
pull_request:
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20, cache: 'npm' }
- run: npm ci
- run: npx turbo build --filter='...[origin/main]'
- run: npx turbo test --filter='...[origin/main]'
自建缓存：实现符合协议的 HTTP 端点 GET/PUT/HEAD /v8/artifacts/:hash（按 teamId 分目录读写产物文件），并在 turbo.json 设 {"remoteCache": {"signature": false}}，运行时指定：
turbo build --api="http://localhost:3000" --token="my-token" --team="my-team"
注意事项
应做：
- 显式声明 inputs，避免无关文件触发缓存失效。
- 用 workspace 协议引用内部包：
"@myorg/ui": "workspace:*"。 - 开启远程缓存，让 CI 与本地共享产物。
- CI 中用
--filter只构建受影响的包。 - 只缓存构建产物，不缓存源文件。
不应做：
- 不要缓存 dev server，应设
persistent: true、cache: false。 - 不要把密钥写进 env 字段，用运行时环境变量。
- 不要漏写 dependsOn，否则任务竞态、缓存键错乱。
- 不要过度过滤，可能漏掉依赖导致构建不完整。
- 输出不能替代环境特定的验证与测试；缺少必要输入、权限或成功标准时先停下来澄清。
互见
- Turborepo 官方文档：https://turbo.build/repo/docs
- 缓存指南：https://turbo.build/repo/docs/core-concepts/caching
- 远程缓存：https://turbo.build/repo/docs/core-concepts/remote-caching
采编自 sickn33/antigravity-awesome-skills（MIT）。