ts-migrate 迁移高频报错排查：10 个常见故障的完整修复清单
【免费下载链接】ts-migrateA tool to help migrate JavaScript code quickly and conveniently to TypeScript项目地址: https://gitcode.com/gh_mirrors/ts/ts-migrate
ts-migrate 是 Airbnb 开源的 JavaScript → TypeScript 迁移工具，通过 codemod 插件把 JS/JSX 项目转成可编译的 TypeScript 项目。本文覆盖从环境安装、tsconfig.json配置到迁移运行阶段的 10 个高频报错，每个条目都给出具体修复动作，10 分钟内可以定位 80% 的启动失败与卡死问题。
排查前的环境自检
按官方流程先跑一次标准安装，避免环境类报错干扰判断：
git clone https://gitcode.com/gh_mirrors/ts/ts-migrate cd ts-migrate yarn yarn build在已有项目里作为依赖使用则是：
npm install --save-dev ts-migrate npx ts-migrate --help- 依赖方式使用：
npx ts-migrate <command> <folder>，四个子命令为init/rename/migrate/reignore - 源码方式使用：仓库是 yarn workspaces monorepo，必须先
yarn再yarn build，否则ts-migrate-plugins、ts-migrate-server等内部包无法解析 - 迁移会读取项目里的
typescript版本，它要求>4.0
⚠️ 最高频的陷阱：先跑
rename或migrate但没先执行init，以及node_modules里的 TypeScript 版本低于 4.0。
核心源码位置（排查时可直接对照）：
- 命令入口与插件列表：
packages/ts-migrate/cli.ts init/rename实现：packages/ts-migrate/commands/init.ts、packages/ts-migrate/commands/rename.ts- 迁移执行主循环：
packages/ts-migrate-server/src/migrate/index.ts
高频故障逐条拆解
先对照速查表定位你的问题，再跳去对应小节：
| 报错关键词 | 问题归类 |
|---|---|
Could not find tsconfig.json at | 配置文件缺失（未 init） |
does not exist | 目录参数错误 |
Error parsing TypeScript config file text to json | 配置文件语法错误 |
Could not find a plugin named | 插件名拼写错误 |
npx报404/ 下载超时 | 网络与 npm registry |
typescript版本提示过旧 | 依赖版本不匹配 |
ts-migrate: command not found | 依赖未安装 |
Cannot find module 'ts-migrate-plugins' | monorepo 构建缺失 |
ts-migrate-fullgit 提交失败 | git 环境未就绪 |
| 运行极长时间无响应 | 项目过大未用--sources |
大量@ts-expect-error和any | 预期产物，非故障 |
Could not find tsconfig.json at—— 没先执行 init
现象：跑rename或migrate时报错退出，提示找不到<folder>/tsconfig.json。
原因：rename和migrate都直接读取folder参数目录下的tsconfig.json来确定文件范围，该文件由init生成，顺序不能反。
修复：
npx ts-migrate init <folder> npx ts-migrate rename <folder> npx ts-migrate migrate <folder>逻辑见packages/ts-migrate/commands/rename.ts，找不到配置直接返回null并以非零码退出。
<folder> does not exist—— 目录参数指错了
现象：init时报错，例如frontend/foo does not exist。
原因：folder参数按当前工作目录解析成绝对路径，写错相对路径或漏了层级时目录不存在。
修复：
- 用
pwd确认当前所在目录 - 把
folder参数改为相对当前目录的正确路径，或直接用绝对路径 - 重跑
npx ts-migrate init <folder>
Error parsing TypeScript config file text to json—— tsconfig.json 不是合法 JSON
现象：rename阶段解析tsconfig.json抛错，附带 JSON 解析错误详情。
原因：tsconfig.json存在语法错误（多余逗号、引号不闭合、include写成对象等），迁移前的解析步骤走的是严格 JSON 转换。
修复：
- 用编辑器打开
tsconfig.json定位语法错误 - 最小化保留
compilerOptions、include、files三块，删掉多余内容 - 重跑原命令；解析逻辑在
packages/ts-migrate/commands/rename.ts的findJSFiles
Could not find a plugin named——--plugin名字拼错
现象：migrate --plugin xxx直接退出，报Could not find a plugin named xxx.。
原因：--plugin必须精确匹配内置插件名，大小写和连字符都不能错。
修复：
npx ts-migrate migrate <folder> --plugin jsdoc合法名字以packages/ts-migrate/cli.ts里availablePlugins数组为准，如jsdoc、react-props、ts-ignore。不确定时去掉--plugin跑全量默认插件链。
npx报404 Not Found或下载超时 —— 网络与 registry 问题
现象：首次用npx ts-migrate时卡在下载，或提示包不存在。
原因：当前网络访问不了配置的 npm registry，或公司代理拦截了 npx 的包解析。
修复：
npm config set registry https://registry.npmmirror.com npm install --save-dev ts-migrate npx ts-migrate --help先本地装好再走npx，可绕开每次的在线解析。
typescript版本过旧 —— 不满足 peer 依赖要求
现象：迁移中 tsserver 初始化异常，或迁移后出现大量与语言版本相关的编译错误。
原因：ts-migrate的peerDependencies要求typescript >4.0，项目里锁了 3.x 或更早版本时语言服务行为不一致。
修复：
npx tsc --version npm install -D typescript@latest确认版本号大于 4.0 后再重跑migrate。
ts-migrate: command not found—— 依赖没装到当前项目
现象：直接敲ts-migrate或ts-migrate-full，shell 说找不到命令。
原因：这两个命令是packages/ts-migrate的bin产物，只有作为 devDependency 安装进项目（或npx拉取）后才存在，不会全局可用。
修复：
npm install --save-dev ts-migrate npx ts-migrate --help npx ts-migrate-full <folder>monorepo 里Cannot find module 'ts-migrate-plugins'—— 内部包没构建
现象：从源码运行 CLI 时报找不到ts-migrate-plugins或ts-migrate-server。
原因：仓库用 yarn workspaces 管理四个包，这些内部依赖指向本地包目录，但包需要先yarn build出build/产物才能被 require。
修复：
yarn yarn build node packages/ts-migrate/build/cli.js --help改了packages/ts-migrate-plugins源码后记得重新yarn build再测。
ts-migrate-full提交失败 —— git 环境未就绪
现象：ts-migrate-full跑完某个步骤后卡在 git 环节，报not a git repository或Author identity unknown。
原因：ts-migrate-full脚本在每一步大操作后会执行git add和git commit作为回滚点，仓库没初始化或没配作者信息就会失败。
修复：
- 在目标目录执行
git init（若还没有仓库） - 配置
git config user.name与git config user.email - 先
git add -A && git commit保证工作区干净，再跑ts-migrate-full
运行极长时间无响应 —— 项目太大，应改用--sources部分迁移
现象：migrate对几万行的大项目跑了很久没有进度感，像卡死。
原因：全量迁移要逐个文件跑 13 个插件，耗时与代码量成正比，官方文档也提示 full migration 可能很久。
修复：
npx ts-migrate-full /path/to/project \ --sources "some/components/**/*" \ --sources "node_modules/**/*.d.ts"用--sources缩小范围分批迁移；注意带上 ambient 类型文件，否则全局类型会被误标为错误。
迁移后大量@ts-expect-error和any—— 预期产物，不是故障
现象：跑完后编译通过，但代码里插满@ts-expect-error注释和any（或$TSFixMe）类型。
原因：工具的设计目标就是"先给出可编译的起点"，推不出类型的地方统一回退到any或压制报错，后续人工细化。
确认方式：
npx tsc --noEmit能过编译即属正常- 之后逐步搜索替换
any与@ts-expect-error完成类型细化 - 若后续升级 TypeScript、React 等库产生新报错，可跑
npx ts-migrate -- reignore <folder>自动重新压制
收尾自查清单
按排查顺序核对，环境 → 配置 → 权限 → 网络 → 功能：
- ✅ Node 与 npm 可用，项目里
typescript版本大于 4.0 - ✅ 目标目录已
init出tsconfig.json，且是合法 JSON - ✅ 源码方式使用时已
yarn+yarn build，内部包构建产物存在 - ✅ 已
npm install --save-dev ts-migrate，npx ts-migrate --help能正常输出 - ✅ 跑
ts-migrate-full前 git 已初始化并配置了user.name/user.email - ✅ 网络能访问 npm registry；大项目已用
--sources分批迁移 - ✅ 迁移后用
npx tsc --noEmit验证编译通过
仍无法解决时，把完整报错文本、命令参数和typescript版本一起提交到项目 issue 区，可参考CONTRIBUTING.md中的贡献流程描述复现步骤。
【免费下载链接】ts-migrateA tool to help migrate JavaScript code quickly and conveniently to TypeScript项目地址: https://gitcode.com/gh_mirrors/ts/ts-migrate
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
