JavaScript / TypeScript / 系统课时

JavaScript 渐进迁移

JavaScript 渐进迁移

把现有 JavaScript 项目一次性改成 TypeScript,通常会同时引入大量类型错误和文件改动。更稳妥的做法是先让 TypeScript 接受 JavaScript,再逐步开启检查、补充 JSDoc,最后按文件迁移到 .ts。

学习目标

  • 使用 allowJs 将现有 JavaScript 文件纳入 TypeScript 项目
  • 使用 checkJs 与 JSDoc 在不改扩展名的情况下获得类型检查
  • 设计从 .js 到 .ts 的可控迁移顺序

先把 JavaScript 纳入项目

allowJs 决定 TypeScript 项目是否允许包含 .js 文件。迁移初期可以先启用它,而保持 checkJs 为 false,这样现有 JavaScript 能进入项目边界,却不会立即因为历史代码产生大量类型诊断。

渐进迁移通常经历“纳入项目、检查 JavaScript、补充类型信息、逐文件改为 TypeScript”几个阶段。每一步都可以独立验证,而不需要一次完成整个代码库。

JavaScript 渐进迁移阶段

迁移起点可以使用下面的配置。noEmit 表示当前只做类型检查,不生成新的 JavaScript 文件,适合在迁移期间先把类型检查接入开发和 CI 流程。

json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

此时 src 中的 .js 和 .ts 都属于项目,但普通 JavaScript 文件还不会全面接受 checkJs 检查。

用 checkJs 和 JSDoc 增加类型约束

当项目已经能被 TypeScript 正常读取后,可以把 checkJs 改为 true。TypeScript 会检查项目范围内的 JavaScript,并识别 JSDoc 中的类型声明,因此很多文件无需立即改名为 .ts 就能获得参数和返回值检查。

下面的 src/math.js 仍然是 JavaScript,但 JSDoc 已经明确了函数契约。

js
/**
 * 计算两个数值之和,让 TypeScript 能在 JavaScript 中检查调用参数。
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function add(a, b) {
  return a + b;
}

const total = add(2, 3);
console.log(total);

将配置中的检查开关改为:

json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

执行项目级检查:

bash
npx tsc

预期输出:

text
无类型诊断,进程正常结束。

如果把调用改成 add("2", 3),TypeScript 就会报告字符串不能作为 number 参数传入。这说明类型检查已经在 .js 文件上生效,而不是必须等到文件改成 .ts 才能发现问题。

控制检查范围而不是一次清零

大型旧项目直接开启全局 checkJs 可能产生过多诊断。此时可以暂时保持全局关闭,并在准备治理的 JavaScript 文件顶部使用 // @ts-check,让检查范围按目录或模块逐步扩大。反过来,个别暂时无法整理的文件也可以短期使用 // @ts-nocheck,但应把它视为迁移债务,而不是永久配置。

JSDoc 最适合补充函数参数、返回值、对象结构和泛型容器等边界信息。对于大量依赖动态属性修改、隐式类型转换或复杂运行时元编程的代码,与其堆积越来越复杂的 JSDoc,通常更适合尽早迁移为 .ts 并重构接口。

按依赖方向逐文件迁移

真正修改扩展名时,优先选择依赖较少、输入输出边界清晰的工具模块。先让这些文件从 .js 变成 .ts,修复其类型错误并保持测试通过,再逐渐迁移调用它们的上层模块。由于 allowJs 仍然开启,已迁移的 TypeScript 与尚未迁移的 JavaScript 可以在同一项目中共存。

每完成一批文件,都运行一次 npx tsc 和现有测试。等主要代码已经迁移后,再删除临时的 @ts-nocheck、收紧过宽的 JSDoc 类型,并评估是否关闭 allowJs。这样类型系统始终是逐步增强的约束,而不会把一次迁移变成难以回滚的大规模重写。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

JavaScript 渐进迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通