TypeScript 7.0 迁移指南

TypeScript 7.0 是自 2012 年以来最大的一次架构变更——微软把整个编译器和语言服务从 TypeScript/JavaScript 移植到了 Go 语言（代号 Project Corsa）。它不是一个”常规大版本”，而是一次底层运行时的彻底替换。

好消息是：**类型检查语义跟 6.0 完全一致。**你的代码如果能在 6.0 的 stableTypeOrdering 下编译通过，在 7.0 也不会有新的类型错误——前提是你已经处理了 6.0 里的所有 deprecation 警告。

坏消息是：7.0 把 6.0 标记为 deprecated 的选项直接变成了硬错误，同时改了核心选项的默认值。如果你从 5.x 跳级到 7.0，中间差了两个版本的破坏性变更，需要处理的事会更多。

升级前的自检：你该不该升？

不是所有项目都应该第一时间升 7.0。做决定之前，先回答三个问题：

问题 1：你的 CI 类型检查有多慢？

如果你的 tsc --noEmit 在 CI 里只需要 3–5 秒，升级 7.0 不会给你带来肉眼可感知的提升——3 秒变 0.3 秒，对人类来说都一样是”做完一杯咖啡之前就过了”。

但如果你的类型检查需要 30 秒以上（大约 300+ 文件的规模），7.0 的 8–12 倍加速会显著改善开发体验。微软内部团队（VS Code、Loop、Office、PowerBI）和生产环境用户（Slack、Canva、Linear、Notion、Vercel）的实测数据都验证了这一点：

项目	TS 6.0	TS 7.0	加速比
VS Code（~170 万行 TS）	125.7s	10.6s	11.9×
Sentry（大型 monorepo）	139.8s	15.7s	8.9×
Bluesky	24.3s	2.8s	8.7×
Playwright	12.8s	1.47s	8.7×
Slack（CI 类型检查）	~7.5min	~1.25min	6×

数据来源：微软官方博客，VS Code/TS 团队内部基准测试。

问题 2：你的项目依赖 TypeScript 编译器 API 吗？

这是 7.0 最大的限制：**暂不提供稳定的编译器 API。**如果你或你的工具链直接 import * as ts from "typescript" 调用编译器 API（ts.createProgram、ts.createSourceFile、自定义 transformer 等），7.0 暂时无法完全满足你的需求。

以下工具在 7.0 GA 阶段需要注意兼容性：

工具	现状	建议
typescript-eslint	依赖编译器 API	继续使用 @typescript/typescript6
ts-morph	依赖编译器 API	继续使用 @typescript/typescript6
ts-loader（完整模式）	依赖编译器 API	转用 transpileOnly 模式 或 Babel
自定义 AST 转换器	依赖编译器 API	等待 7.1 的新 API
ts-node	部分依赖 API	使用 tsx 或 tsimp 替代

微软的策略是让你并存运行：装一个 @typescript/typescript6 包供工具链使用，项目自身的类型检查用 7.0。TypeScript 7.1（预计 2026 年 10 月）会提供新的稳定 API，届时这些工具可以逐步切换。

问题 3：你的项目是 Vue / Svelte / Astro / Angular 项目吗？

如果你用 Vue、Svelte、Astro 或 Angular 做开发，不建议在 7.0 阶段全面升级。这些框架的语言服务实现（Volar、Svelte Language Tools、Astro Language Tools、Angular 模板类型检查）依赖 TypeScript 编译器 API 来分析和处理 .vue / .svelte / .astro 等非标准文件。

微软官方明确表示：

框架项目的建议策略：

框架	建议
纯 React / Next.js / Remix	✅ 可以升级
纯 Node.js 后端	✅ 可以升级
Vue (Volar)	⚠️ 钉在 6.0，等 7.1
Svelte	⚠️ 钉在 6.0，等 7.1
Astro	⚠️ 钉在 6.0，等 7.1
Angular	⚠️ 可用 7.0 做 CLI 检查，编辑器用 6.0

升级清单：13 步完成迁移

以下是按顺序执行的操作清单。每一步都是先检查再改动，不跳步、不偷懒。

第 0 步：确保基线是 TypeScript 6.0

如果你还在用 5.x，先升级到 6.0。6.0 在 ignoreDeprecations: "6.0" 的帮助下可以帮你逐条识别弃用警告而不阻塞构建。修完所有 deprecation 警告后再跳到 7.0。

# 检查当前版本
npx tsc --version

# 如果不是 6.x，先升到 6.0
npm install -D typescript@^6.0.0

# 跑一遍，修复所有 deprecation 警告
npx tsc --noEmit

第 1 步：删除旧的增量构建缓存

Go 编译器的 .tsbuildinfo 文件格式和旧 JS 编译器不兼容。混用会导致奇怪的缓存错误：

# Windows PowerShell
Get-ChildItem -Recurse -Filter "*.tsbuildinfo" | Where-Object { $_.FullName -notmatch "node_modules" } | Remove-Item

# macOS / Linux
find . -name "*.tsbuildinfo" -not -path "*/node_modules/*" -delete

第 2 步：安装 TypeScript 7.0

npm install -D typescript@latest

验证安装：

npx tsc --version
# 应显示 Version 7.0.x

第 3 步：同时保留 TypeScript 6.0（如果需要）

如果你有任何工具依赖编译器 API，安装 6.0 的兼容包：

npm install -D @typescript/typescript6

然后在 package.json 里配置 npm alias：

{
  "devDependencies": {
    "typescript": "^7.0.0",
    "@typescript/typescript6": "^6.0.2"
  }
}

这样 npx tsc 跑的是 7.0，同时 6.0 的 API（tsc6 和 TypeScript 类型导出）对工具链仍然可用。等 7.1 发布后可以逐步移除 6.0 的依赖。

第 4 步：移除已作废的 compilerOptions

以下选项在 7.0 中直接报硬错误，必须删除或替换。逐条检查你的 tsconfig.json：

① target: “es5” / “es3”

// ❌ 删除
"target": "es5"

// ✅ 替换为
"target": "ES2022"  // 或更高

TypeScript 7.0 的 target 最低只接受 ES2015。再也别想输出 ES5 了——2026 年还在用 ES5 target 的项目几乎没有，真要兼容老旧浏览器，让打包工具（Vite/esbuild/Webpack）去做降级处理。

② module: “amd” / “umd” / “system” / “none”

// ❌ 删除
"module": "amd"

// ✅ 替换为（二选一）
"module": "esnext"      // 用 bundler 的话
"module": "preserve"    // 完全不处理模块格式

③ moduleResolution: “node” / “node10” / “classic”

// ❌ 删除
"moduleResolution": "node"

// ✅ 替换为（二选一）
"moduleResolution": "bundler"   // Vite/Webpack/esbuild 项目
"moduleResolution": "nodenext"  // 纯 Node.js 项目（ESM 模式）

④ baseUrl

// ❌ 删除
"baseUrl": "./src"

// ✅ paths 改为相对 tsconfig 目录
// 原来: "paths": { "@/*": ["./*"] }  + "baseUrl": "./src"
// 现在: "paths": { "@/*": ["./src/*"] }

⑤ esModuleInterop / allowSyntheticDefaultImports 设为 false

// ❌ 删除这两行（不能设为 false 了）
"esModuleInterop": false,
"allowSyntheticDefaultImports": false

// ✅ 直接删掉即可——现在只能是 true

⑥ downlevelIteration

// ❌ 删除——已无意义
"downlevelIteration": true

⑦ ignoreDeprecations

// ❌ 删除——7.0 里无效
"ignoreDeprecations": "6.0"

⑧ outFile（配合非 AMD/System module）

// ❌ 删除——大部分场景下已不支持
"outFile": "./dist/bundle.js"

⑨ alwaysStrict: false

// ❌ 删除——alwaysStrict 永远是 true
"alwaysStrict": false

第 5 步：适应新默认值

7.0 改了几个核心选项的默认值。虽然不删也不会报错（只要值本身是合法的），但理解这些变化能帮你避免”怎么输出目录结构变了”的困惑。

strict → 默认 true

最大的变化。如果你本来就没开 strict，现在 7.0 默认开了——你可能会看到一堆之前没见过的类型错误。

这不是 bug，是 TypeScript 在帮你发现潜在的运行时问题。 如果你暂时不想修，可以显式关掉：

{
  "compilerOptions": {
    "strict": false
  }
}

但强烈建议你把它留在 true。之前在 6.0 下可能只是”建议”，现在在 7.0 的性能加持下，修类型错误的效率会高很多。

module → 默认 “esnext”

如果你还在用 CommonJS 输出（很多 Node.js 后端项目），记得显式写：

{
  "compilerOptions": {
    "module": "nodenext"  // 或 "commonjs"
  }
}

rootDir 的默认值变了

TypeScript 7.0 的 rootDir 默认值是 tsconfig.json 所在的目录（即 ./），不像以前一样从输入文件推断。这意味着如果你的源码在 src/ 子目录里，默认输出结构会变：

// 之前（5.x/6.x 推断 rootDir 为 ./src）
dist/
  index.js
  utils/helper.js

// 7.0 默认（rootDir 是项目根）
dist/
  src/
    index.js
    utils/helper.js

修复方式：显式设置 rootDir：

{
  "compilerOptions": {
    "rootDir": "./src"
  }
}

types → 默认空数组

7.0 不再自动引入 node_modules/@types/ 下的所有类型包。你的全局类型（Node、Jest、Mocha 等）需要显式声明：

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

如果你想要恢复旧的”自动引入”行为：

{
  "compilerOptions": {
    "types": ["*"]
  }
}

但官方不推荐这样做——显式声明更清晰、更安全。

第 6 步：配置并行检查器（可选但推荐）

TypeScript 7.0 的实验性并行类型检查可以通过 --checkers 和 --builders 标志控制。这些是 CLI 标志，不写在 tsconfig 里：

# 用 8 个 worker 做类型检查（默认 4 个）
npx tsc --noEmit --checkers 8

# 并行构建多个 project references
npx tsc --build --builders 4

# 完全关闭并行（调试用）
npx tsc --noEmit --singleThreaded

建议在 CI 里逐步试验：

1. 先用默认的 4 个 checker 跑一段时间
2. 观察 CPU 利用率和内存占用
3. 根据 CI 机器的配置调到 6 或 8

// package.json 里的 CI 脚本示例
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "typecheck:ci": "tsc --noEmit --checkers 8 --diagnostics"
  }
}

第 7 步：跑一次完整的类型检查

改完 tsconfig 后，跑一次完整检查：

npx tsc --noEmit 2>&1 | tee ts7-check-output.txt

如果报错很少（小于之前预期），直接修掉即可。如果报错数量惊人，先检查：

• 是不是 strict: true 突然开了？→ 可以暂时关掉，按第 78 章的策略逐步收紧
• 是不是 rootDir 变化导致输出路径混乱？→ 显式设 rootDir
• 是不是某个 @types 包突然不认了？→ 加到 types 数组里

第 8 步：更新 VS Code / 编辑器配置

如果你使用的是 VS Code，安装 TypeScript 7 Language Server 扩展（在 VS Code Marketplace 搜索）。安装完成后，在 .vscode/settings.json 里确认：

{
  "typescript.tsserver.useTs7": true
}

Visual Studio 用户：最新版 IDE 会自动根据工作区的 TypeScript 版本启用 7.0，不需要额外配置。

JetBrains（WebStorm/IntelliJ IDEA）用户：截止 7.0 GA，暂未内置 7.0 的语言服务支持。你可以在命令行用 7.0 做类型检查，编辑器继续使用内置的 6.0 语言服务。

第 9 步：更新 CI 配置

基本不需要改——tsc 命令名不变、tsconfig 结构不变。唯一需要确认的：

• CI 机器上缓存 .tsbuildinfo 文件时，确保 7.0 使用的是新生成的缓存（不是旧 JS 编译器的残留）
• 如果之前 CI 步骤里有显式的 Node.js 版本依赖，7.0 的 Go 原生二进制不再依赖 Node.js 运行时，但你的其他构建步骤可能还需要

# GitHub Actions 示例
- name: Type check
  run: npx tsc --noEmit --diagnostics

第 10 步：做一次性能对比

记录升级前后的性能数据，既能验证收益，也能在团队内部展示成果：

# 升级前（6.0）
npx tsc --noEmit --diagnostics --extendedDiagnostics > ts6-perf.txt

# 升级后（7.0）
npx tsc --noEmit --diagnostics --extendedDiagnostics > ts7-perf.txt

关键指标看这几个：

指标	含义	预期变化
Total time	总编译时间	8–12× 更快
Files	处理的文件数	不变
Memory used	峰值内存占用	降低 10–30%

第 11 步：更新构建脚本（如有特殊需求）

大部分项目的构建脚本不需要改。但如果你之前用了 tsgo（RC 预览版的二进制名），需要全部改回 tsc：

{
  "scripts": {
    "typecheck": "tsc --noEmit",     // ✅ 正式版用 tsc，不是 tsgo
    "build": "tsc --noEmit && vite build"
  }
}

第 12 步：上线后观察

建议在 CI 里临时保留一个 6.0 的并行检查步骤（不阻塞构建），跑 1–2 周确认没有异常后移除：

# GitHub Actions —— 过渡期的并行检查
- name: Type check (TS 7.0)
  run: npx tsc --noEmit

- name: Type check (TS 6.0, safety net)
  run: npx tsc6 --noEmit
  continue-on-error: true  # 不阻塞

第 13 步：移除 6.0 依赖（TypeScript 7.1 发布后）

当 TypeScript 7.1 发布（预计 2026 年 10 月），编译器 API 稳定后，评估你的工具链是否已经适配。确认没问题后，移除 @typescript/typescript6 依赖。

常见升级报错速查

升级过程中可能遇到的报错和对应的修复：

报错	原因	修复
Option 'target=ES5' is not supported	target 设了 es5	改成 ES2022 或更高
Option 'module=amd' is not supported	module 设了 amd	改成 esnext 或 preserve
Option 'moduleResolution=node' is not supported	用了 node 解析	改成 bundler 或 nodenext
Option 'baseUrl' is not supported	配了 baseUrl	移除，paths 改为相对路径
Cannot find type definition file for 'node'	types 默认为空	在 types 数组里加 “node”
Output directory structure differs	rootDir 变了	显式设 rootDir: ”./src”
'this' implicitly has type 'any'	strict 默认 true	给函数加 this 参数标注
Object is possibly 'null'	strictNullChecks 开了	加 null 检查或 ! 非空断言

性能收益验证：你该期待什么

以下是真实项目在 TypeScript 7.0 下的实测数据（来源：微软官方博客）：

项目	TS 6.0 全量构建	TS 7.0 全量构建	加速比	内存变化
VS Code	125.7s	10.6s (4 checkers) / 7.51s (8 checkers)	11.9× / 16.7×	-18%
Sentry	139.8s	15.7s / 12.08s	8.9× / 11.6×	-6%
Bluesky	24.3s	2.8s / 2.01s	8.7× / 12.1×	-26%
Playwright	12.8s	1.47s / 1.16s	8.7× / 11×	-11%

编辑器体验的改善同样显著：

场景	6.0	7.0	提升
VS Code 打开含错文件	~17.5s	<1.3s	~13×
Canva 编辑器初次错误显示	~58s	~4.8s	~12×
Slack 本地编辑器加载	”几乎不可用”	几秒内完成	质的飞跃

框架项目专项指南

React / Next.js / Remix

可以直接升级。 这些框架的 TypeScript 支持不依赖编译器 API，7.0 的 LSP 也完全兼容。升级后编辑器响应和构建检查都会明显变快。

Vue / Svelte / Astro

暂不建议升级。 这些框架的 .vue / .svelte / .astro 文件类型检查依赖 Volar 等工具，而这些工具依赖编译器 API。等 TypeScript 7.1 发布后，官方会与维护者协作推进适配。

在 VS Code 里可以通过命令面板运行 “Disable TypeScript 7 Language Server” 回到 6.0 的语言服务。

Angular

可以部分升级。 Angular 模板的类型检查依赖编译器 API，所以编辑器可能无法使用 7.0。但命令行的 tsc --noEmit 可以用来做项目级的类型检查——这一部分是不依赖模板引擎的。

钉版本的写法

如果决定暂时不升级，在 package.json 里钉住 6.0：

{
  "devDependencies": {
    "typescript": "~6.0.2"
  }
}

等 7.1 发布后重新评估。

最后一章：从入门到上路

这是本书的最后一章，也是最后一节。

回想一下，你从第 1 章”TypeScript 是什么”开始，一路走过了 80 章。你从 let name: string 写到条件类型和映射类型，从 Playground 里的小例子学到 monorepo 的构建管线。现在你手里有了一张完整的操作清单——把一个旧项目升级到 TypeScript 7.0 只需要照着做。

TypeScript 不会停在这里。7.0 是一个新的起点：Go 原生的编译器、并行类型检查、新的 LSP 协议——这套基础设施会让你在未来几年里写 TypeScript 越来越快、越来越爽。7.1 会带来新的编译器 API，更多框架会逐步适配，性能优化还会继续。

你现在要做的不是”记住所有细节”，而是开始用 TypeScript 写东西。写一个项目、改一个旧仓库、给一个开源库加类型声明。类型系统需要在实践中才能真正内化——这本书是一个地图，但走路的人是你自己。

Happy Hacking!

— 码上学，2026 年 8 月