typescript-migration

TypeScript 迁移

TypeScript 5.x → 6 → 7（原生 Go 移植版）的权威迁移指南。内容来源于 Microsoft 官方公告。

状态

• 技能状态：已可用于生产环境
• 最后更新：2026-07-09
• TS 6.0 发布：2026-03-17（正式版）——最后一个基于 JavaScript 的版本
• TS 7.0 发布：2026-07-08——原生 Go 移植版（“Corsa”），稳定版
• 权威来源：
  • TS 7.0 发布公告：https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
  • TS 6.0 Beta 版：https://devblogs.microsoft.com/typescript/announcing-typescript-6-0-beta/
  • TS 6 → 7 差异追踪：https://github.com/microsoft/typescript-go/blob/main/CHANGES.md
  • ts5to6 工具：https://github.com/andrewbranch/ts5to6

黄金法则

绝不要跳过 TypeScript 6。唯一受支持的迁移路径是 5.x → 6 → 7。

跳过 TS 6 会导致大量严重错误，因为 TS 7 会移除 TS 6 中所有已弃用的内容。仅在 TS 6 中将 "ignoreDeprecations": "6.0" 用作临时缓冲；它在 TS 7 中不起作用。

快速初步判断（1 分钟）

1. 检测当前版本——运行 scripts/detect-ts-version.sh（读取 package.json）。
2. 判断迁移路径：
   • 5.x → 从 references/migration-playbooks.md § "5.x → 6" 开始。
   • 6.x → 可直接升级到 TS 7（参见 references/ts7-go-rewrite.md）。
   • 希望从 5.x 升级到 TS 7 → 必须经过 5 → 6 → 7（不能走捷径）。
   • 同一版本内逐步启用严格标志（不更改版本）→ 如需使用可选的 ts-migrating 工具，请参阅 references/ts-migrating-tool-guide.md。
3. 更改任何内容前先审计——运行 scripts/audit-ts7-breakers.sh，检测在 TS 7 下会出问题的工具（typescript-eslint、ts-morph、ts-node、Vue/Svelte/Astro/MDX/Angular 模板、ts-patch、ttypescript、typia、baseUrl、node10、ES5 目标）。

项目类型决策矩阵

项目类型	建议	原因
全新项目，不依赖 API 的工具	直接采用 TS 7	充分提速，没有阻碍
现有 TS 项目，无特殊工具	依次迁移 5 → 6 → 7	TS 6 会先将所有弃用项显示为警告
使用 typescript-eslint / ts-morph / API 消费者	通过 @typescript/typescript6 并行迁移 5 → 6 → 7	TS 7 在 7.1 之前没有编程 API
Vue / Svelte / Astro / MDX（基于 Volar）	留在 TS 6	Volar 需要编程 API；目前尚不支持
使用模板类型检查的 Angular	CLI 使用 TS 7 + 编辑器使用 TS 6	Microsoft 官方提供的拆分方案
ts-patch / ttypescript / typia / 自定义 AST 转换器	留在 TS 6，直到迁移至 Oxc/SWC	TS 7 已移除转换器 API

TS 6 — 主要破坏性更改（速览）

更改	旧默认值	TS 6 默认值	修复方法
strict	false	true	显式设置或修复错误
module	CommonJS	esnext	如有需要，设置为 commonjs
target	ES3	es2025（浮动）	显式设置
moduleResolution	node10	bundler	Node 目标设置为 nodenext
rootDir	推断得出	.（tsconfig 目录）	设置 "rootDir": "./src"
types	所有 @types	[]	设置 "types": ["node"]
esModuleInterop	false	true	移除 :false；将 import * as 修复为 import
noUncheckedSideEffectImports	false	true	修复拼写错误，或为打包器 CSS 设置为 false
libReplacement	true	false	—
allowSyntheticDefaultImports	不定	true	—

在 6 中弃用，在 7 中会导致严重错误：target: es5；downlevelIteration；moduleResolution: node | node10 | classic；module: amd | umd | systemjs | none；baseUrl；esModuleInterop: false；allowSyntheticDefaultImports: false；alwaysStrict: false；outFile；module Foo {} 关键字；导入中的 assert { }；/// <reference no-default-lib="true"/>；在存在 tsconfig 时使用 tsc <file>（改用 --ignoreConfig）。

如需查看各项更改的完整详情，包括 PR 引用、示例和官方 ts5to6 codemod 的用法，请加载 references/ts6-breaking-changes.md。

TS 7 — 变更内容（速览）

• 原生 Go 移植版；标准 typescript npm 包就是 TS 7（npm install -D typescript）。
• 所有 TS 6 弃用项都会变成硬错误（见上表）。
• 7.0 中没有程序化 Compiler API——TS 7.1 将推出新的 API。会影响 ts-morph、ts-node、ts-jest、ts-loader、ts-patch、ttypescript、typia、typescript-eslint（请使用下方的并行安装模式）。
• 移除了 preserveConstEnums——始终会输出 const 枚举。
• stableTypeOrdering 现在默认值为 true；无法关闭。
• 新增标志：--checkers N（默认值为 4）、--builders N、--singleThreaded。
• 新增破坏性变更：模板字面量类型会保留 Unicode 码点（而非 UTF-16 代码单元）。
• 新增：重新设计了 JS 文件处理方式（Closure 风格的 @enum、@class、?、后缀 ! 不再具有特殊含义）。
• 性能（官方数据，真实开源代码库）：构建速度提升 7.7 倍至 11.9 倍（使用 --checkers 8 时最高达 16.7 倍）；内存占用降低 6% 至 26%。

完整安装选项、兼容性矩阵、性能表和已知问题，请参阅 references/ts7-go-rewrite.md。

官方并行安装模式（TS 7 + TS 6 API）

对于工具依赖 TS Compiler API 的项目，Microsoft 推荐使用此方案。在 package.json 中声明别名：

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

• npx tsc 运行 TS 7（通过 @typescript/native 别名）。
• 导入 typescript 的工具（typescript-eslint、ts-morph）会透明地通过 @typescript/typescript6 获取 TS 6 的 API。
• 如果需要直接调用 TS 6，也可以使用 tsc6 可执行文件。
• TS 7.1 推出新 API 后，移除此临时方案。

标准工作流的 4 个步骤

1. 检测 — scripts/detect-ts-version.sh 会报告已安装的版本。
2. 审查 — scripts/audit-ts7-breakers.sh 会在任何升级之前检测破坏性变更。scripts/ts6-deprecation-scan.sh 会从 tsc 输出中提取 TS5xxx 代码。
3. 迁移 — 根据适用的路径，遵循 references/migration-playbooks.md。如果用户明确批准，请运行 ts5to6 --fixBaseUrl 和 ts5to6 --fixRootDir（这些是 Microsoft 官方认可的代码转换工具）。其他所有更改都需手动完成。
4. 验证 — scripts/compare-tsc7-tsc6.sh 会对比 TS 7 tsc 和 TS 6 tsc6 的诊断代码。请按 TSxxxx 代码匹配，而非错误消息文本（不同编译器的措辞有所不同）。首次运行 TS 7 前，请删除过时的 .tsbuildinfo 文件（JS 编译器和 Go 编译器生成的文件彼此不兼容）。

关键规则

始终遵守

• ✅ 通过 TS 6 进行迁移——绝不跳过。
• ✅ 按诊断代码（TSxxxx）匹配，而非错误消息措辞。
• ✅ 首次运行 TS 7 前，删除过时的 .tsbuildinfo 文件。
• ✅ 将 Microsoft 官方博客文章作为权威来源；第三方教程仅作参考。
• ✅ 任何升级之前，都要运行 audit-ts7-breakers.sh。

绝不

• ❌ 绝不将 @typescript/native-preview 用于稳定版——它是旧版 nightly 包；稳定版使用标准 typescript 包。
• ❌ 绝不声称 references/unverified-claims.md 中列出的第三方说法已得到证实（例如“moduleResolution 默认值为 node16”、“存在 --ts6-migration 标志”、“ES5 目标在 6 中已移除”、“--keyofStringsOnly 已移除”）。
• ❌ 绝不推荐使用 ts-migrating（该工具）进行 TS 版本迁移——它只能帮助在同一版本内收紧 compilerOptions。
• ❌ 绝不假设 VS Code 需要设置键才能启用 TS 7——安装官方扩展即可；它会自动启用。
• ❌ 绝不通过自定义脚本自动修改用户源代码——只能使用检测／审查脚本和官方认可的代码转换工具（ts5to6）。

ts-migrating 工具 — 有条件提供

仅当用户想在现有大型代码库中启用更严格的 compilerOption（例如 noUncheckedIndexedAccess、strict、erasableSyntaxOnly）时，才提供此工具——不要用于版本迁移。

必须满足以下所有条件：

• 现有的非绿地 TypeScript 项目。
• 目标是逐步启用 compilerOption。
• 这不是迁移到 tsgo / TS-7。

警告：

• annotate 子命令会重写源代码——请在干净的 git 工作树上运行，并检查差异。
• IDE 插件对 tsc 完全没有影响；要让它发挥作用，请将 ts-migrating check 接入 CI。
• // @ts-migrating 标记属于技术债务，需要进行清理。
• 这不是 Airbnb 的 ts-migrate（这是另一款工具——用于将 JS 转换为 TS）。

完整的安装说明、命令和门槛逻辑见 references/ts-migrating-tool-guide.md。

常见错误代码

代码	含义	操作
TS5011	rootDir 不匹配	设置 "rootDir": "./src"
TS5101	选项已弃用，将在 TS {ver} 中停止支持	添加 "ignoreDeprecations": "6.0"（仅限 TS 6），或修复问题
TS5102	选项已移除	从 tsconfig 中移除
TS5107	选项=value 已弃用	同 TS5101
TS5108	选项=value 已移除	移除
TS5111	迁移信息（baseUrl、node10）	见 references/ts6-breaking-changes.md
TS5112	提供了 tsc 文件参数且存在 tsconfig	使用 --ignoreConfig

何时加载参考资料

当用户需要上述快速参考之外的详细信息时，加载以下参考文件：

加载此文件	适用情况
references/ts6-breaking-changes.md	迁移到 TS 6；需要了解每项默认值变更、弃用或语法变更的完整 PR 引用详情
references/ts7-go-rewrite.md	采用 TS 7；需要安装详情、兼容性矩阵、性能表和已知缺口
references/ecosystem-compatibility.md	检查特定工具（typescript-eslint、ts-morph、ts-node、vite、webpack、vitest 等）是否能在 TS 7 下运行
references/migration-playbooks.md	需要 5→6、6→7 或 5→7（经由 6）迁移的有序检查清单
references/ts-migrating-tool-guide.md	用户想在现有大型代码库中逐步启用更严格的 compilerOption
references/unverified-claims.md	遇到与官方来源相矛盾的说法；在断言前进行核实

依赖项

• 迁移必需：typescript（目标版本）、项目根目录中的 tsconfig.json。
• 可选辅助工具：
  • @andrewbranch/ts5to6 — 用于 baseUrl / rootDir 的官方 codemod。
  • @typescript/typescript6 — 为 TS 7 提供并行 API 兼容性支持。
  • ts-migrating — 逐步启用严格标志（见指南）。

软件包版本（已于 2026-07-09 验证）

{
  "devDependencies": {
    "typescript": "^7.0.2",
    "@typescript/typescript6": "^6.0.2"
  },
  "optionalHelpers": {
    "@andrewbranch/ts5to6": "latest",
    "ts-migrating": "latest"
  }
}

此技能中的所有事实均引用自 Microsoft 官方 TypeScript 博客（devblogs.microsoft.com/typescript）。与官方来源相冲突的第三方教程说法记录在 references/unverified-claims.md 中，并视为可疑。