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”几个阶段。每一步都可以独立验证,而不需要一次完成整个代码库。

迁移起点可以使用下面的配置。noEmit 表示当前只做类型检查,不生成新的 JavaScript 文件,适合在迁移期间先把类型检查接入开发和 CI 流程。
{
"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 已经明确了函数契约。
/**
* 计算两个数值之和,让 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);将配置中的检查开关改为:
{
"compilerOptions": {
"allowJs": true,
"checkJs": true,
"noEmit": true,
"strict": true
},
"include": ["src/**/*"]
}执行项目级检查:
npx tsc预期输出:
无类型诊断,进程正常结束。如果把调用改成 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。这样类型系统始终是逐步增强的约束,而不会把一次迁移变成难以回滚的大规模重写。