ts-migrate 迁移高频报错排查：10 个常见故障的完整修复清单

ts-migrate 迁移高频报错排查10 个常见故障的完整修复清单【免费下载链接】ts-migrateA tool to help migrate JavaScript code quickly and conveniently to TypeScript项目地址: https://gitcode.com/gh_mirrors/ts/ts-migratets-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.tsinit/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配置文件缺失未 initdoes not exist目录参数错误Error parsing TypeScript config file text to json配置文件语法错误Could not find a plugin named插件名拼写错误npx报404/ 下载超时网络与 npm registrytypescript版本提示过旧依赖版本不匹配ts-migrate: command not found依赖未安装Cannot find module ts-migrate-pluginsmonorepo 构建缺失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 folderError 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的findJSFilesCould 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 typescriptlatest确认版本号大于 4.0 后再重跑migrate。ts-migrate: command not found—— 依赖没装到当前项目现象直接敲ts-migrate或ts-migrate-fullshell 说找不到命令。原因这两个命令是packages/ts-migrate的bin产物只有作为 devDependency 安装进项目或npx拉取后才存在不会全局可用。修复npm install --save-dev ts-migrate npx ts-migrate --help npx ts-migrate-full foldermonorepo 里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✅ 源码方式使用时已yarnyarn build内部包构建产物存在✅ 已npm install --save-dev ts-migratenpx 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），仅供参考