migrate-js-to-modern-typescript

JavaScript 到 TypeScript 迁移最佳实践

本指南介绍如何在不进行大规模重写的情况下，将 JavaScript 代码库迁移到严格、现代的 TypeScript。包含 7 个类别中的 42 条规则，并按影响程度排序，以便逐步逐文件迁移，同时确保每一步都能通过构建。

适用场景

在以下情况下可参考这些指南：

• 将 .js 代码库转换为 .ts（整个项目或一次一个模块）
• 通过 JSDoc 或注释为现有 JavaScript 添加类型
• 为混合 JS/TS 仓库选择 tsconfig 和 allowJs 策略
• 在大型代码库中启用 strict 模式或单独的严格选项
• 替换快速转换后遗留的 any、as 类型断言和 ! 断言
• 验证外部数据（JSON、环境变量、API 响应），确保所编写的类型在运行时也成立
• 将 CommonJS 转换为 ESM、将原型转换为类，以及将其他 JS 惯用写法转换为 TS
• 更新构建、运行器和 CI，以进行类型检查并发布 TypeScript

迁移流程

tsconfig & strategy → strictness ratchet → type the surfaces → kill any/casts
   → validate runtime boundaries → convert JS idioms → tooling/build/CI

前期决策会产生连锁影响：错误的 tsconfig 或从上到下的转换顺序，会迫使你对模块重复进行类型标注；而过早大量使用 any，则会污染后续所有内容。请从此流程的前端开始，并从依赖关系图的叶节点向内推进。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	迁移设置与 tsconfig	CRITICAL	setup-
2	逐步收紧严格性	CRITICAL	strict-
3	为公共接口添加类型	HIGH	surface-
4	替换 any 和不安全的类型断言	HIGH	unsafe-
5	运行时数据验证	MEDIUM-HIGH	runtime-
6	将 JS 惯用写法转换为 TS	MEDIUM	idiom-
7	工具链与构建迁移	LOW-MEDIUM	tooling-

快速参考

1. 迁移设置与 tsconfig（CRITICAL）

• setup-allowjs-checkjs-bridge — 启用 allowJs 和 checkJs，以便逐步迁移
• setup-migrate-leaves-first — 先转换依赖关系中的叶节点，再转换依赖它们的模块
• setup-jsdoc-before-rename — 重命名之前，先使用 JSDoc 和 @ts-check 为 JS 添加类型
• setup-prefer-ts-expect-error — 抑制错误时优先使用 @ts-expect-error，而不是 @ts-ignore
• setup-skiplibcheck-during-migration — 设置 skipLibCheck，以屏蔽第三方类型带来的干扰
• setup-modern-module-resolution — 将 module 和 moduleResolution 设置为一组现代配置
• setup-noemitonerror-isolatedmodules — 启用 isolatedModules 和 noEmitOnError，确保安全输出

2. 逐步收紧严格性（CRITICAL）

• strict-enable-flags-incrementally — 一次启用一个严格选项，而不是一次性全部启用
• strict-prioritize-null-checks — 优先启用 strictNullChecks，以尽可能多地发现错误
• strict-no-implicit-any — 启用 noImplicitAny，找出所有未标注类型的值
• strict-no-unchecked-indexed-access — 启用 noUncheckedIndexedAccess，确保索引访问安全
• strict-use-unknown-in-catch — 将捕获的错误类型设为 unknown，而不是 any
• strict-exact-optional-property-types — 使用 exactOptionalPropertyTypes 区分属性缺失与值为 undefined

3. 为公共接口添加类型（高）

• surface-annotate-exported-signatures — 为导出的函数签名显式添加注解
• surface-replace-jsdoc-with-types — 将 JSDoc 类型标签替换为实际类型注解
• surface-type-default-params — 为默认参数和可选参数精确指定类型
• surface-interface-for-object-args — 将宽泛的对象参数转换为具名接口
• surface-type-callbacks — 为回调和高阶参数指定类型
• surface-type-class-fields — 声明类字段类型，而非依赖赋值推断

4. 替换 any 和不安全的类型断言（高）

• unsafe-prefer-unknown-over-any — 在不可信边界处用 unknown 替换 any
• unsafe-eliminate-as-casts — 用类型收窄或验证替换 as 类型断言
• unsafe-avoid-double-assertion — 避免强行转换不相关类型的双重断言
• unsafe-type-dynamic-property-access — 使用 Record 或索引签名为动态属性访问指定类型
• unsafe-replace-function-type — 用具体的调用签名替换 Function 类型
• unsafe-narrow-instead-of-nonnull — 收窄值的类型，而非使用非空断言

5. 运行时数据验证（中高）

• runtime-validate-external-data — 在边界处验证外部数据
• runtime-type-environment-variables — 一次性解析并为环境变量指定类型
• runtime-derive-types-from-schemas — 从运行时模式推导静态类型
• runtime-type-guards-at-boundaries — 为无类型库的返回值编写类型守卫
• runtime-type-json-parse — 通过验证为 JSON.parse 的结果指定类型

6. JS 到 TS 的惯用写法转换（中）

• idiom-require-to-import — 将 require 和 module.exports 转换为 ESM 语法
• idiom-prototype-to-class — 将原型构造函数转换为 class 语法
• idiom-type-only-imports — 使用 import type 进行纯类型导入
• idiom-replace-arguments-object — 用剩余参数替换 arguments 对象
• idiom-enum-to-union-or-const — 将冻结对象枚举转换为 const 对象或联合类型
• idiom-default-export-to-named — 优先使用具名导出，而非默认导出
• idiom-optional-chaining-over-guards — 用可选链替换手动存在性检查

7. 工具与构建迁移（低至中等）

• tooling-declare-untyped-modules — 为无类型依赖提供环境声明
• tooling-install-types-packages — 在强制转换库的返回值之前安装 @types 包
• tooling-use-tsx-over-ts-node — 使用 tsx 直接运行 TypeScript，而非使用 ts-node 标志
• tooling-emit-declaration-files — 为已迁移的库生成声明文件
• tooling-typecheck-in-ci — 在 CI 中添加独立于构建流程的类型检查步骤

使用方法

阅读各参考文件，了解详细说明和代码示例：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则时使用的模板

相关技能

• typescript-refactor — 重构和现代化已有的 TypeScript 代码
• typescript-advanced-patterns — 迁移完成后的高级类型级模式

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息