JavaScript / TypeScript / 系统课时

渐进迁移旧项目

渐进迁移旧项目

渐进迁移的关键不是一次性把所有 .js 改成 .ts,而是先让 TypeScript 接管检查边界,再按目录或模块逐批收紧规则。这样能把隐式 any、空值和第三方类型问题拆成可定位的小任务,同时保持旧代码持续可运行。

学习目标

  • 为 JavaScript 项目建立可逐步收紧的 TypeScript 检查入口
  • 按模块边界安排迁移顺序,并控制每批改动范围
  • 处理隐式 any、空值与第三方依赖三个高频阻塞点

先让 TypeScript 接管而不阻断旧代码

第一阶段只建立“能读取、不过度干预”的编译边界。保留 JavaScript 文件,允许编译器把它们纳入程序图,但先不对所有旧 .js 全量报错;新迁移的 .ts 文件则直接接受严格检查。

json
{
  "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 时,可以直接验证配置:

bash
npx tsc --noEmit

预期结果:

text
<无输出>

退出码为 0 表示当前纳入检查的代码没有 TypeScript 错误;如果迁移文件不满足类型约束,编译器会报告对应文件、行列和错误码。

旧 JavaScript 项目渐进迁移为 TypeScript 的批次流程

按模块边界迁移而不是随机改文件

优先选择依赖少、输入输出清晰的叶子模块,例如工具函数、数据转换层或独立服务。一次迁移一个可测试边界,比随机修改十几个散落文件更容易回滚,也更容易判断新增错误来自哪里。

推荐从很少反向依赖业务代码的模块开始,再逐步向调用方推进。若一个目录同时牵动构建脚本、运行时加载方式和大量动态对象,应先拆小边界,不要为了增加 .ts 文件数量而扩大单批改动范围。

集中处理三类高频阻塞

隐式 any 最容易出现在未标注的函数参数和动态对象上。迁移时先给模块的输入与输出建立明确类型,再处理内部细节;如果暂时无法确定类型,优先使用 unknown 配合类型缩小,而不是让 any 沿调用链扩散。

空值问题应先区分“业务上允许为空”和“历史代码偶然可能为空”。前者在类型中明确写成联合类型并在使用前检查,后者应补初始化或前置校验。不要通过关闭 strictNullChecks 消除错误,否则迁移后仍保留原有空值风险。

第三方依赖先检查包是否自带类型,再检查对应的 @types 包。确实没有声明时,可以增加最小的本地声明作为过渡,但只覆盖当前实际使用的 API,避免把整个模块声明成 any,否则编译器无法继续帮助你收紧边界。

用局部检查提高旧 JavaScript 的质量

尚未改名的 JavaScript 也可以逐文件启用检查。对准备迁移的高价值文件加入 // @ts-check,并用 JSDoc 补少量参数和返回值类型,就能在保持 .js 扩展名的情况下提前暴露问题。

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 等更严格规则。渐进迁移的目标不是长期维持宽松配置,而是让每次收紧都有清晰边界和可验证结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

渐进迁移旧项目

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

登录哪都通