JavaScript / TypeScript / 系统课时
渐进迁移旧项目
渐进迁移旧项目
渐进迁移的关键不是一次性把所有 .js 改成 .ts,而是先让 TypeScript 接管检查边界,再按目录或模块逐批收紧规则。这样能把隐式 any、空值和第三方类型问题拆成可定位的小任务,同时保持旧代码持续可运行。
学习目标
- 为 JavaScript 项目建立可逐步收紧的 TypeScript 检查入口
- 按模块边界安排迁移顺序,并控制每批改动范围
- 处理隐式
any、空值与第三方依赖三个高频阻塞点
先让 TypeScript 接管而不阻断旧代码
第一阶段只建立“能读取、不过度干预”的编译边界。保留 JavaScript 文件,允许编译器把它们纳入程序图,但先不对所有旧 .js 全量报错;新迁移的 .ts 文件则直接接受严格检查。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"allowJs": true,
"checkJs": false,
"strict": true,
"noEmit": true
},
"include": ["src/**/*"]
}这份配置会同时读取 src 下的 .js 和 .ts。checkJs 暂时关闭,因此未迁移的 JavaScript 不会立即产生大批检查错误;strict 则约束已经进入 TypeScript 的代码。noEmit 只做类型检查,不改变旧项目原有的产物链路。
项目已经安装 TypeScript 时,可以直接验证配置:
npx tsc --noEmit预期结果:
<无输出>退出码为 0 表示当前纳入检查的代码没有 TypeScript 错误;如果迁移文件不满足类型约束,编译器会报告对应文件、行列和错误码。

按模块边界迁移而不是随机改文件
优先选择依赖少、输入输出清晰的叶子模块,例如工具函数、数据转换层或独立服务。一次迁移一个可测试边界,比随机修改十几个散落文件更容易回滚,也更容易判断新增错误来自哪里。
推荐从很少反向依赖业务代码的模块开始,再逐步向调用方推进。若一个目录同时牵动构建脚本、运行时加载方式和大量动态对象,应先拆小边界,不要为了增加 .ts 文件数量而扩大单批改动范围。
集中处理三类高频阻塞
隐式 any 最容易出现在未标注的函数参数和动态对象上。迁移时先给模块的输入与输出建立明确类型,再处理内部细节;如果暂时无法确定类型,优先使用 unknown 配合类型缩小,而不是让 any 沿调用链扩散。
空值问题应先区分“业务上允许为空”和“历史代码偶然可能为空”。前者在类型中明确写成联合类型并在使用前检查,后者应补初始化或前置校验。不要通过关闭 strictNullChecks 消除错误,否则迁移后仍保留原有空值风险。
第三方依赖先检查包是否自带类型,再检查对应的 @types 包。确实没有声明时,可以增加最小的本地声明作为过渡,但只覆盖当前实际使用的 API,避免把整个模块声明成 any,否则编译器无法继续帮助你收紧边界。
用局部检查提高旧 JavaScript 的质量
尚未改名的 JavaScript 也可以逐文件启用检查。对准备迁移的高价值文件加入 // @ts-check,并用 JSDoc 补少量参数和返回值类型,就能在保持 .js 扩展名的情况下提前暴露问题。
// @ts-check
/**
* @param {{ name: string, email?: string }} user
*/
export function formatUser(user) {
const email = user.email ?? "unknown";
return `${user.name} <${email}>`;
}片段示例:该文件依赖项目现有的 JavaScript 模块加载环境。启用 // @ts-check 后,错误属性名、明显不匹配的参数类型和部分空值问题会在真正改成 .ts 之前被发现。
为每一批迁移设置验收门槛
一批迁移完成后至少检查三件事:npx tsc --noEmit 通过、原有测试仍通过、运行产物或启动方式没有改变。三个条件同时满足后,再继续扩大 TypeScript 覆盖面,可以把类型问题限制在当前批次内。
当大多数核心模块已经迁移且剩余 JavaScript 的告警可控,再考虑把 checkJs 提升为 true,或进一步启用 exactOptionalPropertyTypes 等更严格规则。渐进迁移的目标不是长期维持宽松配置,而是让每次收紧都有清晰边界和可验证结果。