大型项目 JS 迁移 TS 实战：ts-migrate 工具使用与渐进式重构

大型 JavaScript 项目在向 TypeScript 迁移时，面临的核心困境不是语法本身，而是体量巨大的存量代码与日常业务迭代之间的节奏冲突。若采用“改后缀、改报错”的推倒式重构，成千上万处编译错误足以让持续集成与构建部署彻底瘫痪；而若盲目填充 any 糊弄编译，又会导致类型系统名存实亡。由 Airbnb 开源的自动化迁移工具 ts-migrate，提供了一条“全量快速纳入编译、依赖拓扑逐层消解、CI 守门防退化”的实战路径。本文将详细演示如何使用 ts-migrate 完成工程自动化转换，并落地渐进式重构与质量度量机制。

一、大型项目迁移痛点与 ts-migrate 解决机制

在数万乃至数十万行代码的大型业务工程中，JavaScript 动态特性和复杂的模块调用关系交织在一起。传统的迁移思路往往要求开发者新建独立重构分支，将 .js 或 .jsx 文件批量改为 .ts 或 .tsx，随后尝试逐一消除 TypeScript 编译器（tsc）产生的报错。然而在实际工程中，这种方式通常在第一步就会失控：

• 构建完全阻断：全局执行后缀更名后，编译器通常会抛出数万个类型错误，导致 CI 流水线红屏，业务功能无法正常打包发布。
• 分支周期过长与代码冲突：业务团队每天都有新的功能分支合并入主干。长生命周期的迁移分支一旦脱离主干数周，后续合并将产生海量代码冲突，风险极高。
• 类型污染与虚假安全感：为尽快让工程跑通，开发者极易批量引入 (value as any)。这不仅没有解决类型缺失问题，反而丧失了排查潜在运行时隐患的契机，成为永久遗留的技术债务。

ts-migrate 的破局思路在于将“阻断性错误”转化为“显式技术债务待办”。它借助 TypeScript Compiler API 与 AST（抽象语法树）代码转换工具 jscodeshift，在执行文件批量重命名后，运行插件在所有产生编译报错的代码上方自动插入带有特定错误代码的 // @ts-expect-error TS(xxxx): ... 注解。

在 TypeScript 3.9 及以上版本中，@ts-expect-error 具有一项重要特性：当下方的代码被修复且不再报错时，编译器会主动提示“Unused '@ts-expect-error' directive”警告。这一机制使得迁移后的项目能立即通过 tsc --noEmit 校验，工程可以随时打包发布，而所有历史类型缺陷都被精确记录在代码行中，后续开发者只需按依赖拓扑逐一修复并删除注释即可。

二、工程准备与多语言编译基座打通

在执行任何迁移命令之前，必须先改造底层打包与编译工具链，确保构建系统能够无缝处理同项目中并存的 .js、.jsx、.ts 和 .tsx 文件。

1. 依赖安装与版本锁定

迁移大型工程时，建议精确安装 ts-migrate 及对应版本的 TypeScript 与核心声明包，避免因小版本升级引发 AST 规则变动。在项目根目录下执行以下命令：

npm install --save-dev --save-exact ts-migrate typescript @types/node

# 示例安装输出
+ ts-migrate@0.1.35
+ typescript@5.3.3
+ @types/node@20.11.20
added 142 packages in 8.42s

2. 打包与构建工具链配置

如果项目使用 Webpack 配合 Babel，需在 babel.config.js（或 .babelrc）中补充 @babel/preset-typescript，并在 Webpack 的解析规则中增加 .ts 和 .tsx 扩展名支持：

// babel.config.js 示例配置
module.exports = {
  presets: [
    ['@babel/preset-env', { targets: { browsers: ['>0.25%', 'not dead'] } }],
    '@babel/preset-react',
    '@babel/preset-typescript',
  ],
};

3. 初始阶段宽松 tsconfig.json 策略

迁移初期的目标是让 TypeScript 顺利接管代码，而非立刻启用最高严格模式。初始配置文件应当允许 JavaScript 存量共存，并暂时放宽隐式 any 限制：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "jsx": "react-jsx",
    "allowJs": true,
    "checkJs": false,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "noImplicitAny": false,
    "strictNullChecks": false
  },
  "include": ["src/**/*"]
}

三、ts-migrate 工具链核心指令与实操流程

ts-migrate 采用分步指令设计，将迁移过程明确划分为环境初始化、文件更名、插件流水线迁移三大操作。

1. 步骤一：初始化工程环境（init）

在目标目录执行 init 命令，工具会检测现有环境并生成统一的迁移配置：

npx ts-migrate init ./

# 示例命令输出
[ts-migrate] Initializing TypeScript project in /path/to/project...
[ts-migrate] Created tsconfig.json with base configuration.
[ts-migrate] Created ts-migrate.config.js.

2. 步骤二：批量重命名目标文件（rename）

使用 rename 命令可以按目录或 Glob 通配符逐步推进。该命令会解析文件内部的 AST 语法树，如果检测到 JSX 语法标签（如 <div>），会自动将其重命名为 .tsx，普通模块则重命名为 .ts：

# 仅重命名特定底层目录，例如工具库模块
npx ts-migrate rename ./ --sources "src/utils/**/*.js"

# 示例重命名输出
[ts-migrate] Renaming files in src/utils...
Renamed src/utils/format.js -> src/utils/format.ts
Renamed src/utils/storage.js -> src/utils/storage.ts
Renamed src/utils/dom.js -> src/utils/dom.ts
[ts-migrate] 3 files renamed.

3. 步骤三：运行插件流水线与压制报错（migrate）

重命名完成后立即运行 migrate 命令，此时核心插件链会依次执行代码重构、类成员声明补齐，并在所有类型报错处注入 @ts-expect-error：

npx ts-migrate migrate ./ --sources "src/utils/**/*.ts"

# 示例迁移执行输出
[ts-migrate] Running plugins on 3 files...
Plugin "strip-ts-ignore" executed.
Plugin "hoist-class-statics" executed.
Plugin "declare-missing-class-properties" executed.
Plugin "ts-ignore" inserted 14 error suppression annotations.
[ts-migrate] Migration completed successfully.

4. 核心内置插件解析与配置定制

ts-migrate 允许在 ts-migrate.config.js 中自定义启用的插件与执行顺序。默认插件队列包含了保障代码安全转型的关键步骤：

• strip-ts-ignore：自动扫描并移除历史存留的 @ts-ignore 注释，避免遗留注解干扰本次迁移诊断。
• hoist-class-statics：将以前在 ES6 Class 外部挂载的静态属性（如 MyComponent.displayName = 'MyComp'）自动提升为类内部的 static displayName = 'MyComp' 声明。
• declare-missing-class-properties：根据构造函数中的 this.xxx = yyy 赋值语句，在类顶部自动补全缺失的属性类型声明（如 xxx: any;）。
• ts-ignore / ts-expect-error：调用 TypeScript 编译器诊断，在报错行上方精确注入带有 TS 错误代码的压制注释。

5. 代码迁移前后效果对照

以下为一个典型的网络请求工具模块在迁移前后的对比。迁移后，虽然参数类型未完全人工精细化，但语法已合规，报错被压制且可编译：

// 迁移前：src/utils/request.js
export function fetchData(url, options) {
  return fetch(url, options).then(res => {
    if (!res.ok) {
      throw new Error(res.statusText);
    }
    return res.json();
  });
}

// 迁移后：src/utils/request.ts (由 ts-migrate 自动生成)
// @ts-expect-error TS(7006): Parameter 'url' implicitly has an 'any' type.
export function fetchData(url, options) {
  // @ts-expect-error TS(7006): Parameter 'options' implicitly has an 'any' type.
  return fetch(url, options).then((res) => {
    if (!res.ok) {
      throw new Error(res.statusText);
    }
    return res.json();
  });
}

四、渐进式重构路径：依赖拓扑驱动的分层消解

完成全量文件的后缀重命名与压制注解注入后，工程虽已接入 TypeScript 编译，但此时的代码库充斥着 @ts-expect-error。如何科学地消除这些注解，决定了重构的成败。

在大型工程中，严禁按业务页面（Pages）随机选择文件进行消解。如果底层的工具函数与数据接口未被类型化，上层业务页面在调用时就会得到推导出的隐式 any。这会导致页面开发者反复编写冗余或错误的局部类型，当底层变更时引发连锁破坏。

科学的演进次序应严格遵循依赖拓扑，自底向上分四个层级推进：

1. 第一层：底层工具库与基础类型协议（Utils & Types）
   包括纯函数工具（日期格式化、数学计算、加密解密）、全局常量以及全局类型声明（src/types/globals.d.ts）。这些模块几乎不依赖其他业务代码，优先消除其所有 @ts-expect-error 难度最低，且能立刻为上层模块提供精准的基础推导。
2. 第二层：数据层与 API 传输协议（API & Models）
   定义服务端接口的请求入参与响应体 DTO 接口。通过引入强类型契约，斩断从后端接口流入前端状态存储（Redux/Pinia/Zustand）中的“未知脏数据”。
3. 第三层：通用基础 UI 组件库（Components & Hooks）
   对 Button、Input、Modal 等无业务绑定的原子组件进行重构。将 React 旧有的 PropTypes 替换为标准的 TypeScript interface Props，并为 forwardRef 与自定义 Hook 明确标注返回值泛型。
4. 第四层：复合业务容器与页面路由（Pages & Views）
   在下层基础设施类型完备后，顶层业务页面几乎不需要再手动声明复杂的内部类型，借助 TypeScript 强大的类型推导能力，业务层绝大多数 @ts-expect-error 会在下层修整完毕后直接暴露为“Unused directive”，可一键清理。

五、典型报错消除实战与类型精度提升

在清理 @ts-expect-error 的过程中，开发者会遇到数种高频出现的 TS 错误编号。针对这些场景，应采用针对性的标准解决方案。

1. 场景一：TS2339 / TS2304 全局对象与 Window 注入属性

在老旧 JS 项目中，经常通过 window.__INITIAL_DATA__ 或 window.GLOBAL_CONFIG 访问全局注入对象。在 TS 中这会引发 Property does not exist on type 'Window & typeof globalThis' 报错。

重构解法：避免在代码中写 (window as any).xxx，而是在 src/types/globals.d.ts 中通过声明合并进行扩展：

// src/types/globals.d.ts
export {};

declare global {
  interface Window {
    __INITIAL_DATA__?: {
      userId: string;
      role: 'admin' | 'user';
      token: string;
    };
    GLOBAL_CONFIG: {
      apiBaseUrl: string;
      env: 'development' | 'production';
    };
  }
}

2. 场景二：TS7006 隐式 any 参数与事件处理器收敛

未标注类型的函数参数会触发隐式 any。重构时应精准约束其输入结构，而非简单标注 : any：

// 修复前
const handleChange = (e) => {
  console.log(e.target.value);
};

// 修复后
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  console.log(e.target.value);
};

3. 场景三：缺失类型定义的无维护第三方 NPM 库

部分历史第三方依赖库未提供类型，社区也未维护 @types/xxx。此时应在项目 types/declarations.d.ts 中建立模块桩声明：

// src/types/declarations.d.ts
declare module 'legacy-chart-plugin' {
  export interface ChartOptions {
    width: number;
    height: number;
    theme?: string;
  }
  export function renderChart(containerId: string, options: ChartOptions): void;
}

六、防退化机制、质量度量与 CI 守门

重构中最常见的失败模式是“前脚修复，后脚增生”：一部分开发者在努力消解旧注解，另一部分开发者在日常业务开发中继续提交新的 .js 文件或随意添加压制注解。必须依靠自动化工具与 CI 门禁建立防御体系。

1. 本地研发与提交拦截

在项目中通过 ESLint 与 Git Hooks（如 Husky）对新增代码施加硬性限制：

• 配置 @typescript-eslint/ban-ts-comment 规则，禁止在业务代码中随意书写 @ts-ignore。
• 在 lint-staged 中增加检测脚本，禁止在已完成迁移的目录内新建 .js 或 .jsx 文件。

2. 注解计数与 CI“只减不增”守门脚本

编写轻量级度量脚本，用于扫描全项目并统计 @ts-expect-error 与 @ts-ignore 的实时数量。将基准值写入工程配置文件，并在 CI 流水线中作为合并卡点：

// scripts/check-ts-errors.js
const fs = require('fs');
const path = require('path');
const glob = require('glob');

const MAX_ALLOWED_ERRORS = 1420; // 初始记录的基线总数

const files = glob.sync('src/**/*.{ts,tsx}');
let totalErrors = 0;

files.forEach(file => {
  const content = fs.readFileSync(file, 'utf8');
  const matches = content.match(/@ts-(expect-error|ignore)/g);
  if (matches) {
    totalErrors += matches.length;
  }
});

console.log(`当前项目 TS 压制注解总数: ${totalErrors} (基线上限: ${MAX_ALLOWED_ERRORS})`);

if (totalErrors > MAX_ALLOWED_ERRORS) {
  console.error(`[CI 守门失败]: 压制注解数量超出上限，请先修复类型问题，严禁引入新注解！`);
  process.exit(1);
} else if (totalErrors < MAX_ALLOWED_ERRORS) {
  console.log(`[优化提示]: 恭喜！已成功消解 ${MAX_ALLOWED_ERRORS - totalErrors} 处注解，请同步调小 MAX_ALLOWED_ERRORS 基线值。`);
}

在 CI 流水线（如 GitHub Actions、GitLab CI 或 Jenkins）中配置两道强制校验：

# CI 执行指令示例
npm run type-check   # 执行 tsc --noEmit，保障整体编译退出码为 0
node scripts/check-ts-errors.js  # 执行只减不增校验

3. 局部开启严格模式（tsconfig.strict.json）

当某一核心模块（如 src/utils/ 或 src/api/）的所有压制注解完全清零后，可以通过子配置文件对其先行挂载严格模式，防止后续修改破坏类型质量：

// tsconfig.strict.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  },
  "include": [
    "src/utils/**/*",
    "src/api/**/*",
    "src/types/**/*"
  ]
}

在 CI 中并行运行 tsc --project tsconfig.strict.json --noEmit。这种“化整为零、逐区加固”的方式，能稳步推动整个代码库走向 strict: true 终态。

七、总结与工程迁移实践速查

大型 JavaScript 项目向 TypeScript 的迁移绝非一蹴而就的语法改造，而是一项包含工程架构、流水线基建与团队规范的系统性演进。下表梳理了基于 ts-migrate 的全周期关键阶段、交付物与验证指标：

阶段名称	核心操作与执行命令	阶段关键产出	验证与验收指标
阶段一：基座准备	安装依赖、配置 Babel/Webpack 解析规则、生成初始宽松 tsconfig	构建工具同时支持 .js 与 .ts	存量 JS 业务正常打包、无运行时退化
阶段二：机械迁移	ts-migrate init ts-migrate rename ts-migrate migrate	文件重命名完成，生成 @ts-expect-error 注解	tsc --noEmit 退出码为 0，业务正常上线发布
阶段三：分层消解	自底向上拓扑消解：Utils → API → Components → Pages	替换为精准 Interface，消除压制注解	未使用的压制指令被 TS 编译器主动告警并移除
阶段四：防御闭环	ESLint 限制、Pre-commit 卡点、CI 计数脚本、“只减不增”门禁	注解燃尽看板、tsconfig.strict.json 子配置	无新增 JS 文件，注解总数单向递减，关键目录 strict 达标

通过“以 ts-migrate 快速突破冷启动阻断、以 @ts-expect-error 精确量化债务、以依赖拓扑科学消解、以 CI 门禁锁死防线”四部曲，团队能够在保障业务零中断的前提下，安全、平滑且可预测地完成大型工程的 TypeScript 重构改造。