企业官网建设流程全解析

react-spring 单仓从 Yarn 3 迁移到 pnpm 的研究记录：版本锁定、严格隔离与构建脚本白名单的八项关键决策

【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring

本文为 react-spring 单仓（monorepo）包管理器迁移（Yarn 3 Berry → pnpm）在实施前的 Phase 0 研究成果解读，覆盖版本与锁定机制、workspace 清单形态、postinstall 脚本策略、CI 缓存等八项关键决策（R-001 至 R-008），并结合仓库中已落地的 根 package.json 与 pnpm-workspace.yaml 等配置文件佐证其最终形态，帮助读者掌握一次「不换架构、只换包管理器」迁移的完整研究方法论与可复制操作清单。

1. 背景：一次「只换包管理器，不改任何其他东西」的结构性迁移

本次迁移的功能定义见 spec.md：将yarn@3.8.7（nodeLinker: node-modules扁平提升布局）整体替换为 pnpm 的严格隔离node_modules布局，并配套完成 lockfile、workspace 清单、packageManager锁定、CI 工作流、下游消费示例（fixture）等全部配置面的切换。plan.md 明确了迁移范围：16 个 workspace（packages/与targets/下的库、demo与docs）、5 个 GitHub Actions 工作流、5 个下游消费者 fixture，且要求以单个 PR 原子落地，「不存在有中间态价值」的半迁移状态。

research.md 是该迁移的 Phase 0 输出，回答实施前必须拍板的 8 个研究问题（R-001 到 R-008）。每一条决策都遵循「Decision（决策）+ Rationale（理由）+ Alternatives considered（被否方案）」的三段结构。下文逐条展开，并给出当前仓库中的落地证据。

2. R-001：pnpm 大版本选择与版本锁定机制

决策：采用迁移 PR 打开时点 pnpm9.x 的最新稳定版，通过根package.json的packageManager字段（"packageManager": "pnpm@9.<x>.<y>"）锁定，并由 Corepack 激活。

研究文档给出的三条理由：

1. pnpm 9 是当时的稳定线——虽然 pnpm 10 已发布但生态采纳仍在磨合期；而 9 已经提供了迁移所依赖的三个能力：严格的node-linker=isolated、确定性 lockfile 格式 v9、以及onlyBuiltDependencies构建脚本白名单（见 R-003）；
2. packageManager字段 + Corepack 与 Yarn 3 现行锁定方式（"packageManager": "yarn@3.8.7"+.yarn/releases/yarn-3.8.7.cjs）是同构的约定，现代 Node 均支持corepack enable；
3. 锁定单一版本可以消除 lockfile 漂移这一类 CI 偶发失败（flake）。

被否方案：pnpm 10.x（「集成方还在追赶」的噪声超过了迁移这种以「不出意外」为目标的工作的边际收益，推迟到后续升级）；只用engines.pnpm而不写packageManager（贡献者环境间不可靠，且 Corepack 感知型工具恰恰以packageManager为准）；全局安装 pnpm 不走 Corepack（贡献者环境会漂移，违背锁定的初衷）。

仓库佐证：当前 根 package.json 即为"packageManager": "pnpm@9.15.9"，与研究决策完全一致——迁移后贡献者与 CI 通过 Corepack 自动收敛到同一个 pnpm 版本。

3. R-002：pnpm-workspace.yaml的形态

决策：用独立的pnpm-workspace.yaml替代根package.json中的workspaces字段：

# pnpm-workspace.yaml packages: - 'packages/*' - 'targets/*' - 'demo' - 'docs'

同时删除既有的packages/parallax/@react-spring/parallax-demo条目——该目录在仓库中已不存在（packages/parallax/下只有src/、test/等）。

理由：这是一个从旧布局遗留下来的「死重量」。Yarn Berry 对失效的 workspace 路径静默容忍，而 pnpm 会对缺失路径告警/报错，顺手清理即可；其余 4 个 glob 覆盖了构建当前实际使用的所有 workspace。

被否方案：保留失效条目「以防万一」（研究文档直言这是「六个月后咬你一口的静默腐化」，故拒绝）；用逐 workspace 的显式路径替代 glob（glob 形态与 Yarn 时期一致，且新包目录可被自动纳管，故拒绝）。

仓库佐证：当前仓库根目录的 pnpm-workspace.yaml 恰好就是这 4 条 glob，逐字未变——R-002 的决策已被原样采纳。

4. R-003：pnpm 9+ 下的 postinstall 构建脚本白名单

决策：在根package.json中显式声明pnpm.onlyBuiltDependencies白名单。研究文档给出的起始清单（best-guess starter）为：

"pnpm": { "onlyBuiltDependencies": [ "@swc/core", "cypress", "esbuild", "@remix-run/dev", "@parcel/watcher", "core-js", "core-js-pure" ] }

核心动机：pnpm 9 默认阻止依赖的安装/postinstall 脚本；没有白名单时，需要原生构建的包（@swc/core、esbuild、cypress等）虽然会装上，但跳过其 post-build 步骤，造成运行期失败。根目录自身的"postinstall"脚本属于根级生命周期而非依赖脚本，不受此机制影响，予以保留。研究文档特别强调：起始清单只是猜测，真正的清单要在安装时收敛——pnpm 9 会精确打印被忽略脚本的告警，逐个将确实需要构建的包加入白名单，直到告警列表对「需要构建的包」为空。

被否方案：unsafe-perm之类全局关闭安全检查（这恰是应当尊重而非绕过的正确性设置，拒绝）；维护独立的.pnpm-allowlist文件（package.json才是正确归属：已提交、可评审、作用域限定在仓库内）。

仓库佐证与演化：当前 根 package.json 的最终白名单收敛为：

"pnpm": { "onlyBuiltDependencies": [ "@parcel/watcher", "@swc/core", "core-js", "core-js-pure", "es5-ext", "esbuild" ] }

对比可见 R-003「以安装告警为准、迭代收敛」方法论的实际效果：cypress与@remix-run/dev在最终清单中消失，es5-ext被补入——从当前仓库脚本看（如 根 package.json 的test:unit已基于 vitest、devDependencies 中为playwright而非cypress），这与仓库工具链后续演进相吻合。研究决策的「先猜后收敛」流程在真实仓库中得到验证。

5. R-004：Huskyprepare脚本在 pnpm 下的行为

决策：原样保留既有的"prepare"生命周期脚本。prepare是标准 npm 生命周期钩子（并非 yarn 专属），pnpm 在pnpm install时与 yarn 一样会执行它；Husky 的钩子接线命令本身也不依赖包管理器。因此无需任何额外动作，唯一验证点是：全新pnpm install之后 pre-commit 与 commit-msg 钩子能够正常触发。

被否方案：把 Husky 换成simple-git-hooks或lefthook——超出范围，迁移目标是「只换包管理器，其他不变」。

仓库佐证：当前 根 package.json 中"prepare": "husky"仍然存在且承担同一职责（Husky 9 的新式调用形式），印证了「生命周期不变、仅验证行为」的结论。相关验收在>- uses: pnpm/action-setup@v4 # 版本来自 package.json 的 packageManager —— 无需 `version:` 输入。 - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node }} cache: 'pnpm' - run: pnpm install --frozen-lockfile

缓存 key 自动从pnpm-lock.yaml推导。

理由：pnpm/action-setup是 GitHub Actions 中安装 pnpm 的推荐方式，自动尊重packageManager锁定，让 CI 与贡献者锁步；actions/setup-node内置的 pnpm 缓存覆盖全局 store；既有的cache: 'yarn'只是换一词为cache: 'pnpm'。

被否方案：用corepack enable手动装 pnpm（可行但多一步，且放弃了pnpm/action-setup的缓存层）；手写actions/cachekey（脆弱且没必要）。

contracts/ci-commands.md 进一步补充了操作细节：Setup pnpm步骤必须位于Setup node之前（因为setup-node的cache: 'pnpm'要求 pnpm 已在 PATH 上）；Linux runner 上 pnpm 全局 store 位于~/.local/share/pnpm/store/v3，由setup-node负责缓存；并给出了五个工作流的改写迭代顺序（checks.yml→bundle-size.yml→tests.yml→experimental.yml/nightly.yml）。

10. 研究如何驱动落地：从 research.md 到可执行任务

research.md 的 8 项决策并非孤立结论，而是被下游设计文档逐条消费：

• data-model.md 把决策物化为 8 个「配置面实体」（E1 lockfile、E2 workspace 清单、E3 包管理器锁、E4 安装/hoist 配置、E5 CI 缓存、E6 Husky 接线、E7 下游 fixture、E8 文档面），每个实体都定义了前置状态、后置状态与验证规则，并明确「不存在有效中间态」——迁移要么在严格隔离下干净安装，要么还需要更多 workspace 声明；
• contracts/developer-commands.md 与 contracts/ci-commands.md 分别固化开发者与 CI 两侧的命令契约，「迁移后仍出现 yarn 形式即视为缺陷」；
• quickstart.md 把 R-007/R-008 的成果转写为贡献者 onboarding 文本：corepack enable→pnpm install→ 日常命令表，并专门解释了严格隔离的行为差异（遇到Cannot find module 'foo'应声明依赖而非加 hoist 规则）；
• tasks.md 再将其拆为 T001–T065 的依赖序任务图，其中 Phase 2 的「发现性安装 + 并行幽灵依赖修复 + 收敛重装」正是 R-006 方法论的直接执行。

11. 小结：可复制的迁移研究清单

以 react-spring 这次 Yarn 3 → pnpm 迁移为样本，一次结构型包管理器迁移的研究阶段需要回答并落档的问题可以归纳为：

1. 大版本与锁定：选哪个 pnpm 大版本，用什么机制（packageManager+ Corepack）保证贡献者与 CI 收敛；
2. workspace 清单：新清单的 glob 形态，顺手清理失效条目；
3. 构建脚本策略：用onlyBuiltDependencies显式白名单应对 pnpm 9 的默认脚本阻断，且接受「起始清单 → 安装告警 → 收敛」的迭代过程（当前 package.json 的最终清单就是这一过程的产物）；
4. 生命周期钩子：确认prepare（Husky）等标准 npm 生命周期在 pnpm 下等价执行，无需迁移；
5. 下游消费面：CI 中的消费者 fixture 独立于主仓选型，选最低公分母（npm）降低 CI 面；
6. 幽灵依赖暴露面：列出每个 workspace 的疑似缺失声明，把首次安装当发现步骤，以定向修复替代全局 hoist；
7. 命令映射：逐条给出 yarn → pnpm 的等价命令并固化为契约文档；
8. CI 缓存：pnpm/action-setup+cache: 'pnpm'的标准块，以及步骤顺序约束（pnpm 先于 node setup）。

这套「决策 + 理由 + 被否方案 + 仓库佐证」的研究记录结构，配合 spec.md 的验收场景与 quickstart.md 的验证流水线，构成了一个可被其他 monorepo 直接套用的迁移研究模板。

【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring