企业官网建设流程全解析

• 构建工具
• 开发工具
• CLI

本文基于 turbo 仓库（Build system optimized for JavaScript and TypeScript, written in Rust）锁文件测试套件中的bun-v1-issue-12653复现工程，完整还原"turbo prune --docker生成的out/json/bun.lock在 Docker 构建中被bun install --frozen-lockfile拒绝"的真实故障场景。读完本文，你将掌握该 bug 的完整复现步骤、每条错误信息的含义、bun.lock 中版本作用域（scoped entry）导致解析失败的具体机理，以及 turbo 仓库如何用锁文件 fixture 体系持续回归这类问题。

一、背景：turbo prune --docker与 Bun 锁文件的组合为何值得关注

turbo prune是 turbo 提供的"按目标工作区裁剪"能力：给定一个目标 workspace（如@eventmate/migrations），它会递归计算出依赖它的全部 workspace 与外部依赖，生成一个只包含必要文件的目录，供 CI / Docker 构建使用。其中--docker模式会将输出拆分为两个目录：

• out/json/：裁剪后的package.json与锁文件（供安装阶段使用）；
• out/full/：裁剪后的完整源码（供构建阶段使用）。

当 monorepo 使用 Bun 作为包管理器时，out/json/中会出现裁剪后的bun.lock。安装阶段通常配合--frozen-lockfile保证可复现构建。问题恰恰出现在这里：裁剪后的 bun.lock 可能是"结构上合法、语义上不可解析"的——这也是本文 fixture 要复现的核心故障。lockfile-tests/fixtures/bun-v1-issue-12653/README.md 明确写道：该仓库"intentionally keeps source code minimal while preserving the relevant workspacepackage.jsondependency graph from the original project"，即用最小化源码保留真实的依赖图，以便稳定触发问题。

二、复现工程解剖：fixture 的目录结构与关键配置

fixture 位于 lockfile-tests/fixtures/bun-v1-issue-12653/，目标镜像是一个 Prisma 迁移服务（migration service）：

lockfile-tests/fixtures/bun-v1-issue-12653/ ├── apps/ │ ├── admin|api|bot|docs|frontend|marketing/ # 各 package.json │ └── migrations/ # 目标工作区 │ ├── Dockerfile │ ├── docker-entrypoint.sh │ └── package.json ├── packages/ │ ├── audit|metrics|permissions|stripe-listener|ui/ │ ├── database/ │ │ ├── index.ts │ │ ├── package.json │ │ ├── prisma.config.ts │ │ └── prisma/{schema.prisma, migrations/} │ └── ... ├── bun.lock ├── bunfig.toml ├── meta.json ├── package.json └── turbo.json

meta.json：驱动测试套件的元数据

meta.json 声明了测试所需的全部关键信息：

{ "packageManager": "bun", "packageManagerVersion": "bun@1.3.13", "lockfileName": "bun.lock", "frozenInstallCommand": [ "bun", "install", "--frozen-lockfile", "--ignore-scripts" ], "pruneTargets": ["@eventmate/migrations"] }

• pruneTargets指定裁剪目标为@eventmate/migrations，与 Dockerfile 中的turbo prune @eventmate/migrations --docker一致；
• frozenInstallCommand与 Dockerfile 安装阶段的命令完全对齐，说明 fixture 刻意模拟真实 CI 的安装参数。

bunfig.toml：hoisted 链接模式

bunfig.toml 内容极简但关键：

[install] linker = "hoisted"

它强制 Bun 使用 hoisted（提升）链接模式。这会影响 bun.lock 中依赖的存放形态：满足版本约束的依赖被提升到根级，无法提升的版本则记录为路径作用域条目（如@eventmate/database/recharts/...）。这是理解后文根因的重要前提。

package.json：依赖图的关键特征

根 package.json 声明了packages/*与apps/*两个 workspace 通配，包管理器为bun@1.3.13，并使用了 Bun Catalog（catalog:、catalogs:字段）与overrides。真正把问题引出来的，是 packages/database/package.json 中这一条：

"dependencies": { "@prisma/adapter-pg": "catalog:", "@prisma/client": "catalog:", "dotenv": "catalog:", "pg": "catalog:", "recharts": "^3.1.2" }

而目标工作区 apps/migrations/package.json 依赖@eventmate/database（workspace:*）：

"dependencies": { "@eventmate/database": "workspace:*", "dotenv": "catalog:" }

于是裁剪@eventmate/migrations会连带拉入@eventmate/database，进而拉入recharts@^3.1.2——这个间接依赖正是崩溃的导火索。README 还特别说明，Prisma 包的存在是为了匹配迁移服务的 Docker 镜像形态，而--ignore-scripts用于在裁剪后的源码被拷贝进来之前阻止postinstall（packages/database/package.json 中有"postinstall": "bun run generate"）提前执行。

三、复现步骤：从 Docker 构建到安装阶段的失败

完整复现命令（README 原文）：

docker build --no-cache -t turbo-bun-prune-frozen-repro -f apps/migrations/Dockerfile .

Dockerfile 采用标准多阶段构建，问题发生在installer阶段：

FROM oven/bun:1.3.13-alpine AS base WORKDIR /app FROM base AS pruner RUN bun add -g turbo@2.9.7-canary.13 COPY . . RUN turbo prune @eventmate/migrations --docker FROM base AS installer COPY --from=pruner /app/out/json/ . RUN bun install --frozen-lockfile --ignore-scripts # ← 失败点 COPY --from=pruner /app/out/full/ . RUN cd packages/database && bun run generate FROM base AS runner COPY --from=installer /app ./ RUN chmod +x ./apps/migrations/docker-entrypoint.sh WORKDIR /app/apps/migrations CMD ["./docker-entrypoint.sh"]

流程要点：

1. pruner阶段用bun add -g turbo@2.9.7-canary.13安装 turbo 并执行turbo prune --docker，产出out/json/（含裁剪后的 bun.lock）与out/full/；
2. installer阶段先拷贝out/json/，随即执行bun install --frozen-lockfile --ignore-scripts；
3. 预期结果：该命令失败，且失败发生在 Prisma generation 之前（COPY --from=pruner /app/out/full/ .之后才会执行bun run generate）；
4. 最终runner阶段通过 docker-entrypoint.sh 执行bun run migrate:deploy，即 Prisma 迁移部署。

四、失败现象逐条解读

在oven/bun:1.3.13-alpine与turbo@2.9.7-canary.13组合下，观察到的完整错误输出为：

error: Failed to resolve prod dependency 'eventemitter3' for package 'recharts' InvalidPackageInfo: failed to parse lockfile: 'bun.lock' warn: Ignoring lockfile error: lockfile had changes, but lockfile is frozen

可见失败的"靶心"是第一条：裁剪后的锁文件中，recharts与eventemitter3之间的依赖记录对 bun 而言不可解析，后续的InvalidPackageInfo/Ignoring lockfile/ frozen 报错都是连锁反应。

五、对照组：根锁文件本身是有效的

为了证明问题出在"裁剪"而非"锁文件本身"，README 给出了一个关键对照实验——直接用根目录的原始 bun.lock 执行相同的安装参数：

docker run --rm -v "$PWD:/work" -w /work oven/bun:1.3.13-alpine bun install --frozen-lockfile --ignore-scripts

结论：根锁文件有效，该命令可以正常通过。失败只会在turbo prune --docker生成out/json/bun.lock之后出现。这一"对照组"设计思路在 turbo 的锁文件测试运行器中有对应实现：doValidate会先在未裁剪的原始 fixture上执行一次包管理器校验，只有原始 lockfile 与其 package.json 匹配，才继续测试turbo prune的输出（见 runners/local.ts）。

六、从 bun.lock 结构推断根因

要理解裁剪为何会破坏解析，需要看 bun.lock 中 recharts / eventemitter3 的记录形态（以下行号基于当前仓库文件实测）：

1. 根级提升的 recharts@2.15.4（bun.lock#L3350）依赖eventemitter3: ^4.0.1，对应根级条目eventemitter3@4.0.7（bun.lock#L2298）；
2. 路径作用域的 recharts@3.8.1：@eventmate/database/recharts与@eventmate/ui/recharts都解析到recharts@3.8.1（bun.lock#L3938、bun.lock#L3950），它们的依赖是eventemitter3: ^5.0.1；
3. 对应的 eventemitter3@5.0.4被记录为@eventmate/database/recharts/eventemitter3（bun.lock#L4724）与@eventmate/ui/recharts/eventemitter3（bun.lock#L4736）。

可以推断的机理如下：

• apps/migrations的裁剪会保留@eventmate/database（它是 workspace 依赖），因此裁剪后的锁文件需要包含@eventmate/database视角下的recharts（即@eventmate/database/recharts→ recharts@3.8.1），而recharts@3.8.1 要求eventemitter3@^5.0.1；
• 根级提升的eventemitter3@4.0.7只满足 recharts@2.x 的^4.0.1，无法满足^5.0.1；满足要求的 5.x 条目@eventmate/database/recharts/eventemitter3是"随父包路径作用域"记录的；
• 裁剪器在生成out/json/bun.lock时，@eventmate/ui被正确剪掉，但@eventmate/database/recharts/eventemitter3这类路径作用域条目与其父节点recharts的关联未被完整保留，导致 bun 在解析 recharts 的依赖时找不到eventemitter3，最终报出Failed to resolve prod dependency 'eventemitter3' for package 'recharts'。

这正是 hoisted linker 下"根级版本 + 路径作用域版本并存"的典型陷阱：裁剪器对 bun.lock 的路径作用域条目（scoped entries）处理不完整，生成的文件对 bun 而言是"非法锁文件"，而非单纯的版本不满足。需要说明的是，以上根因分析基于当前仓库 bun.lock 的结构推断，fixture 本身定位为"可稳定复现的失败样本"；该缺陷是否在后续 turbo / bun 版本中修复，仓库内并未声明。

七、该 fixture 在 turbo 锁文件测试体系中的角色

bun-v1-issue-12653是 turbo 仓库lockfile-tests回归体系的组成部分。该体系的入口是 check-lockfiles.ts：

"End-to-end validation that turborepo's lockfile pruning produces lockfiles that package managers accept without downloading packages."

其运行方式为：将每个 fixture 拷贝到临时目录 → 对每个目标 workspace 执行turbo prune（支持--docker/--production变体）→ 用对应包管理器在裁剪产物目录校验锁文件。使用方式：

pnpm check-lockfiles # 全部 fixture pnpm check-lockfiles --fixture bun-v1-issue-12653 # 只跑该 fixture pnpm check-lockfiles --pm bun # 只跑 bun 系列 pnpm check-lockfiles --turbo-path ./path/to/turbo # 指定 turbo 二进制

关键实现细节（见 runners/local.ts）：bun 的校验命令是

case "bun": { return { command: "bun install --frozen-lockfile", env: { BUN_CONFIG_SKIP_INSTALL_PACKAGES: "1" } }; }

BUN_CONFIG_SKIP_INSTALL_PACKAGES=1让 bun 只做锁文件解析校验、不真正下载安装包，从而在 CI 中快速判断"裁剪后的锁文件能否被 bun 接受"。types.ts定义了PackageManagerType（含bun）、TestCase、TestResult等类型；expectedFailures字段则允许显式声明"已知会失败的 workspace"。fixture 目录命名bun-v1-issue-12653遵循"包管理器 + 版本 + 上游 issue 号"的惯例——同目录下还有bun-v1-issue-10410、bun-v1-issue-12156、bun-v1-issue-12252等一系列 Bun 锁文件问题样本，共同构成针对 Bun 生态的持续回归防线。

八、排障与规避思路

基于本次复现，可以总结出几条可操作的排障路径：

1. 先验证"锁文件 vs 依赖图"是否自洽：如果bun install --frozen-lockfile报出Failed to resolve ... for package ...，优先检查报错包（这里是recharts）在其所有作用域条目中声明的依赖版本，是否都能在锁文件中找到对应条目；
2. 区分"原始锁文件有效"与"裁剪锁文件有效"：用docker run直接在根目录执行相同安装命令做对照（即 README 的 Control 实验），可以快速定位问题出在 prune 阶段；
3. 检查out/json/的裁剪产物：turbo prune --docker后查看out/json/bun.lock，重点核对被保留包（如@eventmate/database/recharts/...）的路径作用域条目是否完整、其依赖节点是否可达；hoisted linker 下"根级 4.x + 路径级 5.x 并存"的形态尤其容易在裁剪时丢条目；
4. 结合--ignore-scripts的语义排查：--ignore-scripts会跳过所有生命周期脚本（本例中是 database 包的postinstall: bun run generate），避免在源码拷贝进来前触发 Prisma 生成——若去掉该参数，错误信息会被后置的生成失败掩盖，干扰定位；
5. 用最小 fixture 复现：本 fixture 的做法值得借鉴——保留真实依赖图、删减无关源码，并把"目标镜像形态"（Prisma 迁移服务）还原为最小 Dockerfile，从而把复杂 monorepo 的构建失败压缩成可一键复现的最小样本。

综上，bun-v1-issue-12653是一个"过程正确、结果非法"的锁文件裁剪案例：原始 bun.lock 完全有效，turbo prune --docker也能正常产出，但裁剪后的out/json/bun.lock丢失了recharts@3.8.1所需的eventemitter3@^5.0.1路径作用域条目，最终被bun install --frozen-lockfile以InvalidPackageInfo+ frozen 冲突的形式拒绝。理解这一机理，不仅能帮你排查同类 Bun + Turbo Docker 构建问题，也能更深刻地理解锁文件裁剪器在处理 hoisted linker 产物时面临的语义挑战。

• 构建工具
• 开发工具
• CLI