YApi 还能跑，为什么还要迁？
这是我们在做迁移评估时被问得最多的一句话。答案不是“Apifox 功能更多”，而是 YApi 停更后，安全漏洞、升级维护、权限审计、跨团队协作这些问题，慢慢从“能忍”变成“不能忍”。
但迁移本身并不轻松。我们原以为导出再导入就完了，结果前后折腾了几轮。下面这 6 个坑，是这次迁移里最值得记录的。
说明：以下来自一次中型研发团队的脱敏迁移复盘，团队名和具体数字做了处理。
坑 1：把迁移当成“导出再导入”
现象：接口是导进去了，但目录乱了、模型重复了、示例丢了，前端打开文档第一句话是“这跟原来不一样啊”。
原因：YApi 的目录、接口、数据模型、环境变量、权限是几套东西，导入工具只能搬“结构”，搬不了“语义”。
做法：
- 先冻结旧平台写入，避免迁移过程中还在改。
- 导出后先做一份接口清单，标记核心/非核心、负责人、调用方。
- 按“目录 → 接口 → 数据模型 → 环境 → 权限”的顺序核对。
- 先迁一个非核心项目做样板，再批量迁。
坑 2：权限照搬，结果没人能改
现象：迁移后，原来能编辑的人变成了只读，原来只读的人反而能改；管理员看不到某些项目。
原因：YApi 的角色模型和 Apifox 的多团队/多项目权限不是一一对应。直接按用户名映射，很容易错位。
做法：
- 先列一张角色映射表：YApi 的 owner/developer/guest 对应 Apifox 的什么角色。
- 按“团队 → 项目 → 成员”重建，不要只按人迁。
- 迁移后用几个真实账号做权限验证：能看、能改、能发布、能管理。
- 对敏感项目单独做一次权限复核。
坑 3：环境变量和鉴权脚本没迁
现象：接口能打开，但一调试就 401；有的接口在旧平台能跑，新平台一直提示 token 无效。
原因：YApi 的环境变量、全局 header、登录脚本，和 Apifox 的环境/变量/前置脚本不是自动等价的。
做法：
- 先把旧平台的环境变量导出成清单。
- 在 Apifox 里重建开发/测试/预发/生产环境。
- 把 token 获取、签名、公共 header 放到前置脚本或公共参数。
- 不要把所有值都写死在接口里，用变量引用。
- 迁移后跑一遍“登录 → 查询 → 修改”的最小链路。
坑 4：Mock 地址一变，前端联调断了
现象：后端说“Mock 已经迁好了”，前端说“我这边全是 404”。
原因：前端代码、低代码平台、测试环境里写死了旧 YApi 的 Mock 地址。迁移只改了平台，没改调用方。
做法：
- 迁移前全局搜索旧 Mock 域名。
- 列出所有引用方：前端项目、测试环境、自动化脚本、合作伙伴。
- 能改代码的改代码，不能改的做反向代理/域名跳转。
- 保留旧地址一段时间，设下线时间表。
- 用真实前端页面做一次联调验收。
坑 5：文档迁移了，但没人对它负责
现象：迁移完成后一个月，文档又开始过期。新同事问“这个字段什么意思”，没人答得上来。
原因：旧平台有历史包袱，大家习惯了“文档是给别人看的”。迁移只是换了地方，没有换责任。
做法：
- 每个核心项目指定一个文档 owner。
- 把“接口变更必须更新文档”写进合并请求检查项。
- 用规范检查工具做第一轮把关。
- 每周看一次文档更新率，而不是只看迁移数量。
- 新人入职培训里加一段“怎么找接口、怎么改文档”。
坑 6：没有并行期，一刀切引发反弹
现象：旧平台一关，群里立刻炸锅：有人找不到接口，有人不会用新平台，有人抱怨“还不如原来”。
原因：迁移是技术动作，切换是组织动作。没有并行期，所有问题都集中在切换当天爆发。
做法：
- 旧平台保留只读一段时间，至少覆盖一个迭代。
- 新平台先让试点团队用起来，形成样板。
- 切换前做分角色培训：后端、前端、测试、管理员。
- 准备一份“常见问题 + 找谁求助”的文档。
- 设一个明确的旧平台下线日期，提前通知。
迁移清单（可以直接照抄）
迁移前
- 冻结旧平台写入
- 导出接口清单和负责人
- 梳理环境变量、鉴权脚本
- 搜索旧 Mock 地址引用
- 定角色映射表
- 选试点项目
迁移中
- 先迁目录和核心接口
- 再迁数据模型和公共 Schema
- 重建环境变量
- 配置 Mock 和测试场景
- 校验权限
- 跑最小链路
迁移后
- 前端联调验收
- CI/自动化脚本验收
- 文档 owner 确认
- 旧平台只读并行
- 培训和答疑
- 下线旧平台
最后一点感受
YApi 迁移最难的不是工具，而是“习惯”。
工具可以把接口搬过去，但搬不了“文档要及时更新”“接口变更要通知”“测试要进流水线”这些习惯。迁移项目如果想一次成功，最好把技术迁移和组织推广一起做，而不是等上线后再补。
如果你也在做类似迁移，建议先选一个团队、一个项目跑通，再复制。别追求“一次性全量”，那通常是最慢的路径。