Cypress 中基于 esbuild 的依赖打包器 @tooling/packherd：把 V8 Snapshot 流水线的前半程讲清楚

导读

@tooling/packherd 是 Cypress 仓库中负责"依赖打包"（Bundling）的工具包：它从给定的入口文件出发，调用 esbuild 将全部可达的 Node.js 依赖打成单个 bundle，并同时返回 bundle Buffer、esbuild metafile 元数据、可选的 source map Buffer 以及 esbuild warnings。它构成了 Cypress V8 Snapshot 打包流水线的"前半程"——负责产出 bundle，而"后半程"（运行时加载）由 @packages/packherd-require 承担。阅读本文后，你将掌握 packherd 的完整 API、其分层架构中六个模块各自的职责、入口文件生成的巧妙机制，以及在 Cypress 构建启动性能优化链路中的真实调用位置。

一、packherd 在快照流水线中的位置

packherd 官方定位是 V8 Snapshot 流水线的打包半程：运行时加载半程位于 @packages/packherd-require。二者的分工如下：

1. 打包应用文件并产出相关元数据——由本包（@tooling/packherd）提供；
2. 加载此前已被打包的模块（这些模块以完全实例化的 exports 或"调用后返回 exports 的定义函数"形式提供）——由 @packages/packherd-require 提供；
3. 按需转译 TypeScript 模块并维护缓存——同样落在 @packages/packherd-require。

其中 1、2 紧密配合、协同工作；3 与打包无关，只是因为它同样需要拦截模块加载，才一并归入 packherd-require。packherd 产出的 bundle 可被调用方保存或继续加工，例如 tooling/v8-snapshot 会用它先产出初始 bundle，再交给快照生成器与 doctor 处理——这正是"以指定文档为主体、仓库源码佐证"的集成点。仓库内 guides/v8-snapshots.md 描述了整个快照方案，可作为背景延伸阅读。

二、快速上手：关键命令

@tooling/packherd 的 package.json 中提供了如下脚本：

yarn build              # 用 tsc 将 TypeScript 编译到 dist/
yarn check-ts           # 仅做类型检查，不产出文件（tsc --noEmit）
yarn watch              # tsc 监视模式（tsc --watch）
yarn clean              # 删除 dist/（rimraf dist）
yarn clean-deps         # 删除 node_modules（rimraf node_modules）

# 默认 test 就是跑集成测试
yarn test

# 运行某个具体的集成测试文件
yarn test-integration -- <path-to-spec>

# 按名称模式过滤集成测试
yarn test-integration -- --grep "<pattern>"

注意：默认的 yarn test 只运行集成测试（本包没有独立的单元测试），并且集成测试会真实构建 bundle，耗时相对较长。测试通过 mocha 执行，配置文件为 ./test/.mocharc.js（见 package.json 的 test-integration 脚本）。

三、架构：src 下的六个模块

文档明确指出 src/ 下共六个模块，逐个结合源码展开：

1. packherd.ts — 公共入口

公共入口 src/packherd.ts 导出 packherd 函数，接收 PackherdOpts，返回 bundle、meta、sourceMap 与 warnings。其执行流程如下：

1. 选取 createBundle（默认取 create-bundle.ts 中的默认实现，也可由调用方注入）；
2. 实例化 EntryGenerator，传入 createBundle、入口文件、nodeModulesOnly 与 pathsMapper，调用 createEntryScript() 生成合成入口脚本源码字符串 entry；
3. 通过 tmpFilePaths() 拿到临时输出路径（os.tmpdir()/packherd/bundle.js），以 outdir 指向该目录；
4. 调用 esbuild，使用 stdin 方式喂入生成的入口源码：
   • stdin.contents 为生成的入口内容，sourcefile 设为目标入口文件，resolveDir 设为其所在目录，同时强制开启 metafile: true；
5. 断言 metafile 非空、outputFiles 长度为 1 或 2（注释解释：使用 stdin 时 esbuild 会把同一输出文件以 .../stdin.js 和 .../entry.js 两个路径重复上报一次）；
6. 取第一个 outputFiles 作为 bundle 内容（Buffer），sourceMapFile 存在时同样转为 Buffer。

返回对象的完整字段（源码 packherd.ts）：

字段	类型	含义
bundle	Buffer	最终打好的依赖包内容
sourceMap	Buffer | undefined	配置生成时的 source map，否则为 undefined
meta	esbuild Metafile	描述被打包资产（inputs 及其 bytes/imports）的元数据
warnings	esbuild BuildResult['warnings']	esbuild 打包过程中发出的警告

2. create-bundle.ts — 调用 esbuild 的核心封装

src/create-bundle.ts 实现默认的 bundle 函数，直接调用 esbuild 的 build API。关键点：

• 内建默认项 platform: 'node'、target: ['node22']；
• 通过 Object.assign 合并调用参数后强制追加 bundle: true、write: false（不写盘、纯内存产出，这正是 packherd 能拿到 outputFiles 内容的前提）；
• 以 entryPoints: [entryFilePath] 指定入口，并在传给 esbuild 前删除自定义字段 entryFilePath（避免 esbuild 因未知选项抛错）；
• 注释特别提醒 esbuild 输出文件要么带 text: string、要么带 contents: UInt8Array，二者不会同时出现——因此 packherd.ts 中做了 Buffer/字符串双分支转换。

3. generate-entry.ts — 生成合成入口文件

这是整个包的精髓：src/generate-entry.ts 中的 EntryGenerator 会先借助 getMetadata 跑一次 esbuild 拿到 metafile，再把从入口可达的全部依赖"拍平"成一份合成入口脚本。每一行形如：

exports['./node_modules/isobject/index.cjs.js'] = require('./node_modules/isobject/index.cjs.js')

这样做的价值在注释里讲得很直白：诊断问题时方便——想排除某个依赖，直接在生成的入口文件里注释掉对应行即可。流程细节：

• 过滤掉 packherd 自身（!x.includes(packherd)），避免把自己的源码打进包；
• nodeModulesOnly 为 true（构造器默认值）时只保留路径含 node_modules 的输入；
• 统一把 node_modules/... 前缀修正为 ./node_modules/...，再交给 pathsMapper（默认恒等映射）做路径改写；
• 相对入口目录解析路径、排序、转换为 POSIX 分隔符，拼接出以 // vim: set ft=text: 开头的入口文本。

pathsMapper（(s: string) => string）配合 nodeModulesOnly 让你精确控制最终进入 bundle 的文件集合。构造函数签名：(createBundle, entryFile, nodeModulesOnly = true, pathsMapper = identityMapper)。

4. get-metadata.ts — 解析 esbuild metafile

src/get-metadata.ts 的作用是以"只取元数据"为目的再跑一次 esbuild：以 outfile: '<stdout:out>'、outbase 指向入口目录发起构建，只取 metafile 返回。下游 EntryGenerator 正是用它推导出依赖图，进而构建自定义入口文件。这也解释了为何 packherd 对同一入口会触发两次 esbuild 调用（一次纯取元数据、一次真正出包）。

5. types.ts — 共享类型定义

src/types.ts 集中定义公开类型，并被 packherd.ts 以 export * from './types' 对外再导出：

• CreateBundleOpts——esbuild BuildOptions 的扩展，额外要求 entryFilePath: string；
• CreateBundleOutputFile / CreateBundleSourcemap——包装 esbuild OutputFile['contents']；
• CreateBundleResult——warnings、outputFiles、可选 sourceMap 与 metafile；
• CreateBundle——允许调用方覆盖默认 bundle 函数的函数签名；
• PackherdOpts——entryFile（必填，被打包应用的 index 文件路径）、nodeModulesOnly（为 true 时只打进 node_modules）、pathsMapper、createBundle（见 packherd.ts）。

6. utils.ts — 临时文件工具

src/utils.ts 提供 tmpFilePaths()：在 os.tmpdir()/packherd 下确保目录存在，并返回 bundle.js 输出路径，供主流程作为 esbuild outdir。

四、测试验证：从集成测试反推行为

包内两个集成测试文件验证了上述行为：

• test/packherd.spec.ts：基于 @tooling/system-tests 提供的 v8-snapshot/minimal fixture 真实出包，断言 meta.inputs 精确等于 node_modules/isobject/index.cjs.js、node_modules/tmpfile/index.js 与 entry.js，校验各输入字节数下限、entry.js 的 import 关系（kind: 'require-call'）、以及 bundle 长度下限；还通过桩 createBundle 覆盖测试了注入自定义 bundle 函数的路径。
• test/entry-generator.spec.ts：用同样的 fixture 断言 createEntryScript() 产出的 paths 与 entry 文本与预期完全一致（含排序与 exports[...] = require(...) 逐行格式），并验证在 metafile 混入非 node_modules 输入时按默认 nodeModulesOnly 过滤的行为。

五、工程细节与注意事项（Gotchas）

文档中值得注意的三点工程经验，均能在源码与 package.json 中得到印证：

1. esbuild 是运行时依赖而非 devDependency。因为 @tooling/v8-snapshot 会在打包时刻以编程方式调用 esbuild（见 package.json 的 dependencies），若误降级为 devDependency，消费方安装后无法解析 esbuild。

2. package.json 的 files 字段同时包含 dist 与 src/packherd.ts，而 "types" 直接指向 src/packherd.ts。这样下游消费者无需单独的 .d.ts 生成步骤即可获得正确类型（package.json）。由于类型引用依赖源码文件随包发布，files 中必须保留该源码。

3. 同一输出被 esbuild 上报两次：使用 stdin 出包时 outputFiles 会出现 .../stdin.js 与 .../entry.js 两份，代码以断言（长度为 1 或 2）与"取第一个文件"的方式消解该行为（packherd.ts）。

六、集成点一览

• @tooling/v8-snapshot（tooling/v8-snapshot）是首要消费者：它调用 packherd 产出初始 bundle，快照生成器与 doctor 再基于该 bundle 继续处理。因此理解 packherd 的返回结构（bundle Buffer + metafile + sourceMap）是理解 Cypress V8 Snapshot 启动加速方案的前提。
• 运行时半程 @packages/packherd-require（packages/packherd-require）：负责从本包产出的 bundle 中加载模块，并提供按需 TS 转译与缓存。

简言之：packherd 负责"把依赖在构建期一次性打成一个可被快照化的 bundle"，packherd-require 负责"运行时把这些模块原样装载起来"，二者共同支撑 Cypress 通过 V8 Snapshot 显著缩短冷启动/加载时间的目标。

七、如何在 Cypress 仓库内做实验

packherd 是 monorepo 内的私有包（"private": true），无法独立对外发布。若想在仓库内验证其行为，可参考集成测试的做法：

1. 利用 @tooling/system-tests 脚手架搭建 fixture 项目（如 v8-snapshot/minimal），并安装其 node_modules；
2. 在 tooling/packherd 目录下直接调用 packherd({ entryFile })，观察返回的 bundle Buffer、meta.inputs 与 warnings；
3. 结合 @tooling/v8-snapshot 的引导脚本把 packherd 的输出继续喂给快照生成链路，复现完整的"打包 → 快照 → 运行时加载"流程。

依赖 esbuild 0.28.x（"esbuild": "^0.28.1"），目标运行平台为 Node（platform: 'node'），代码按 node22 编译目标处理。

---

说明：本文全部结论均以当前仓库 tooling/packherd 下的 AGENTS.md、README.md、源码与集成测试为依据；其中"运行时加载与 TS 按需转译"、"下游快照生成器与 doctor"等跨包描述来自文档的集成点声明，可结合 packages/packherd-require 与 tooling/v8-snapshot 继续深入。