7.2 迁移策略与互操作

7.2 迁移策略与互操作

本节摘要：工具迁移的失败从来不是"装不上"，而是半途状态留下的暗伤：两把锁并存、目录残骸、流水线各节不同步。本节给出迁移的四步标准流程——预检、换锁、验证、切换——配上回滚预案与团队节奏控制，并单独立一条最高禁令：同一仓库禁止两把锁并存。读完你应能把一次工具切换变成一场有预案的常规工程动作。

从一次半途而废的迁移说起

先看反面教材。某团队决定从 Yarn 换到 pnpm，负责人的动作是：装上新工具，删掉 yarn.lock，跑 pnpm install，能用，宣布完成。两周后问题接连出现：一位同事没拉最新代码，本地还有旧的 yarn.lock，他顺手用 Yarn 装了个新依赖——仓库里从此并存两把锁，各自描述不同的事实；流水线里一个缓存步骤还在按 Yarn 的缓存目录缓存，命中了一堆对 pnpm 无效的旧数据；新人克隆仓库，README 写的安装命令与配置文件指向的工具不一致，装了三遍才成功。

复盘的关键句：迁移不是切换工具，而是切换"事实源"——锁文件、配置、文档、流水线缓存，全都指向旧工具的事实源必须一次性、全体、同时换掉。半途状态比旧状态更危险，因为它让团队在两个事实源之间精神分裂。

四步标准流程

第一步：预检。 迁移前先盘点三件事。目标工具的版本策略（锁文件格式是否稳定、与当前运行时的兼容性）、仓库的非常规形态（工作区、私有源配置、发布流程——7.1 节的横评矩阵过一遍）、以及团队的使用面（文档、脚本、习惯里有多少地方提到了旧工具）。预检的产出是一份迁移清单：要动的文件、要改的配置、要通知的人。

第二步：换锁。 用目标工具的导入能力生成新锁，绝不用手写：

# 从 Npm 迁到 pnpm 为例
$ pnpm import          # 读取 package-lock.json 生成 pnpm-lock.yaml
$ rm package-lock.json # 新锁验证通过后再删旧锁（顺序不能反）
$ rm -rf node_modules  # 清掉旧工具的目录残骸
$ pnpm install         # 全新安装
​

注意命令顺序的讲究：先生成新锁、验证通过、再删旧锁——旧锁在回滚窗口内是唯一的退路。清单文件（package.json）通常不需要改动，这也是三家互操作性的重要一环：清单格式基本互通，锁格式互不相认。

第三步：验证。 新环境下的全量验证：完整安装、完整测试、本地跑一遍核心流程，有条件的话在隔离分支跑一次完整流水线。验证清单里别漏三处：锁文件已入库且旧锁已从版本库删除；项目级源配置与新工具的配置格式匹配；持续集成配置里的安装命令、缓存目录、脚本管控全部换新——缓存目录这处最容易漏，正如开头事故所示。

第四步：切换与公告。 验证通过后在团队低活跃时段合入，同一批动作里更新文档（安装命令、贡献指南）、公告全员、并设一个回滚窗口（比如一周）——窗口内保留回滚分支，出问题按预案退回。

图 7-2 迁移四步与回滚预案

互操作的现实：混用的边界

"清单互通、锁不互通"的规则决定了混用的安全边界。可以偶尔：在别的机器上临时用另一家工具跑个一次性脚本（不提交它生成的锁文件变更）。不可以长期：同一仓库两批人各用各的工具——每次安装都在改写不同的事实源，3.2 节的求解幂等与执行幂等双双作废。绝对不可以：两把锁并存且都被提交（如开头事故）。这条边界的判定物很明确：版本库里最终提交了什么事实源，而不是谁在什么机器上敲了什么命令。

工作区仓库的迁移还有一处加成：顶层一把锁统管全部子包（5.1 节），迁移动作本身与单包仓库无异，但验证面扩大到每个子包——发布流程、内部版本号、发布预演都要在新工具下重跑一遍。

团队节奏控制

工具迁移的组织学比技术学更难。三条经验值得搬走。其一，一次只迁一件事。 换工具的窗口期内冻结依赖升级（暂停机器人），避免迁移与升级的问题互相污染归因。其二，迁移要有一名所有者。 分布式负责等于无人负责，所有者对清单、验证、公告全权负责。其三，把新工具的收益制度化。 迁移完成不是终点——把目标工具的优势写成团队规约（比如 pnpm 的脚本白名单策略、Yarn 的工作区发布流程），否则换来的能力很快在惯性中闲置，迁移变成纯成本。

迁移成功的标志不是"新工具装上了"，而是三个月后没人再提起旧工具——文档、流水线、肌肉记忆全部完成换代。

迁移验收单

切换完成不等于迁移完成——下面这张单子全部打勾才算。事实源项：版本库里只剩一把锁；项目配置只指向新工具；文档与贡献指南的命令全部替换。流水线项：安装命令、缓存目录、缓存键全部换新且完整跑绿一次；锁文件漂移检查与两把锁检测已经挂上。团队项：全员本地的旧工具残留配置已公告清理；回滚分支在窗口期保留且有明确销毁日期；新工具的核心收益已写成至少一条团队规约（比如脚本白名单默认开启）。复盘项：迁移过程中踩到的坑记入团队知识库——下一次换工具（也许在几年后）会感谢这份记录。

验收单的逻辑与 6.2 节的提速验收单同源：把"完成"定义成可核对的状态，而不是一种感觉——感觉会骗人，勾选框不会。

三个时间维度的风险管理

迁移的风险管理按时间轴拆成三段，各有一份清单。迁前一周：冻结依赖升级（暂停机器人）、盘点非常规配置（工作区、私有源、发布流程）、在隔离分支完整演练四步流程——演练发现的每一条都写进迁移清单。迁移当天：低活跃时段合入、全员公告同步发出、流水线关键节点盯守第一轮构建——当天的目标不是"完成"，是"第一轮全绿"。迁移后一个月：观察三项指标——安装失败率、平均安装时长、依赖类求助次数；任一指标劣化先查新工具配置，再考虑是否触发回滚预案。观察期结束，销毁回滚分支，迁移正式归档。

把风险按时间轴切碎，每一块都小到可管理——迁移失败的项目，几乎都是在"迁移当天"才发现前两段没做。

本节要点回顾

• 迁移的本质是切换事实源：锁、配置、文档、流水线缓存必须一次性全体换掉，半途状态比旧状态更危险；
• 四步流程：预检出清单、导入换锁（旧锁是退路）、全量验证（别漏流水线缓存）、低峰切换加回滚窗口；
• 最高禁令：两把锁并存——防线靠流水线检测强制，不靠自觉；
• 混用边界：清单互通、锁不互通；判定物是版本库里提交的事实源；
• 组织三经验：一次只迁一件事、指定所有者、把新工具收益制度化。

路径也走完了，最后一节把视线抬到时间轴上：这个领域接下来往哪去——哪些趋势会改写今天的选型答案，哪些判据能帮你看清未来。