TypeScript 7.0 Beta 迁移笔记：tsconfig 默认值、硬错误清单与 Strada API 空窗

TypeScript 7.0 把现有 TypeScript 代码库从 TypeScript 移植到了 Go，并未重写；类型检查逻辑与 6.0 在结构上一致。移植版跑过十年前留下的测试套件，也已在微软内外部多个百万行级代码库中使用。原生代码加共享内存并行通常带来约 10 倍速度提升，但迁移面才是重点。

项目信息：

• 公告：https://devblogs.microsoft.com/typescript/announcing-typescript-7-0-beta/
• 12 月进展：https://devblogs.microsoft.com/typescript/progress-on-typescript-7-december-2025/
• 代码库：https://github.com/microsoft/typescript-go
• VS Code 博客：https://code.visualstudio.com/blogs/2026/06/26/iterating-faster-with-ts-7

安装与并行运行

npm install -D @typescript/native-preview@beta
npx tsgo --version
# Version 7.0.0-beta

用 tsgo 替代 tsc。包名最终会回到 typescript，稳定版 7.0 以 typescript 发布，并使用 tsc 入口。

兼容包 @typescript/typescript6 暴露 tsc6 入口，re-export TypeScript 6.0 的 API。typescript-eslint 这类工具通过 peer dependency 直接 import typescript，所以推荐用 npm 别名让两套包并存：

npm install -D typescript@npm:@typescript/typescript6

或写进 package.json：

"devDependencies": {
  "typescript": "npm:@typescript/typescript6@^6.0.0"
}

稳定的编程 API 最早要到 TypeScript 7.1。

兼容性判定

在 TypeScript 6.0 下能干净编译的代码（开启 stableTypeOrdering、不启用 ignoreDeprecations），在 7.0 下应编译出相同结果。7.0 沿用 6.0 的新默认值，并对 6.0 中已废弃的选项和写法给出硬错误。

一、tsconfig 默认值变化

• strict 默认 true
• module 默认 esnext
• target 默认当前稳定 ECMAScript 版本，即紧邻 esnext 之前的那个版本
• noUncheckedSideEffectImports 默认 true
• libReplacement 默认 false
• stableTypeOrdering 默认 true，且无法关闭
• rootDir 默认 ./，内部源码目录必须显式设置
• types 默认 []；要恢复旧行为需设成 ["*"]

两处常见 diff：

{
  "compilerOptions": { + "rootDir": "./src" },
  "include": ["./src"]
}

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

二、被降为硬错误的旧开关

这些选项在 7.0 里不再支持，行为等同 no-op：

• target: es5 不再支持
• downlevelIteration 不再支持
• moduleResolution: node / node10 不再支持；改用 nodenext 或 bundler
• module: amd / umd / systemjs / none 不再支持；打包器或浏览器模块解析场景用 esnext 或 preserve
• baseUrl 不再支持；paths 改为相对项目根目录，而不是相对 baseUrl
• moduleResolution: classic 不再支持；用 bundler 或 nodenext
• esModuleInterop、allowSyntheticDefaultImports 不能设为 false
• alwaysStrict 视为 true，不能设为 false
• namespace 声明里不能用 module 关键字
• import 上不能用 asserts 关键字，改用 with，与 ECMAScript import attributes 对齐
• skipDefaultLibCheck 下不再识别 /// 指令
• 当前目录存在 tsconfig.json 时，命令行构建不能直接传文件路径，除非显式加 --ignoreConfig

三、工具链 API 空窗

Corsa（TS 7.0）不支持现有的 Strada API。依赖它的 linter、formatter、IDE 扩展无法在 Corsa 上工作。变通方式是并排安装 typescript 和 @typescript/native-preview：工具链走 ≤6.0 的 API，类型检查交给 tsgo。前面那段 npm 别名就是为这个准备的。稳定的编程 API 最早在 7.1 出现。

JavaScript / JSDoc 差异

JSDoc 支持重做过，与 .ts 分析保持一致：

• 期望类型的位置不能放值，写 typeof someValue
• @enum 不再特殊识别；在 (typeof YourEnumDeclaration)[keyof typeof YourEnumDeclaration] 上建 @typedef
• 单独的 ? 不能再当类型用，改用 any
• @class 不会把函数变成构造函数，改用 class 声明
• 不支持 postfix !，用 T
• 类型名必须定义在 @typedef 标签内，不能紧贴在标识符旁边
• Closure 风格函数语法 function(string): void 不再支持，改用 TypeScript 简写 (s: string) => void
• 把 this 起别名、整体重赋函数 prototype 这类写法不再特殊处理

CHANGES.md 记录了更细的差异。

迁移顺序

按兼容性前提，实际迁移可以这么走：

1. 先把项目升到 6.0 并编译干净，开启 stableTypeOrdering，去掉 ignoreDeprecations。
2. 用 ts5to6 处理 baseUrl 与 rootDir：

npx @andrewbranch/ts5to6 --fixBaseUrl your-tsconfig-file-here.json
npx @andrewbranch/ts5to6 --fixRootDir your-tsconfig-file-here.json

1. 对照上面的硬错误清单逐项改配置，重点是 module 与 moduleResolution。
2. 装 @typescript/native-preview@beta，用 tsgo 对同一份代码跑类型检查，与 tsc 输出对比。

进展与当前限制

12 月进展：约 20,000 个编译器测试用例中，约 6,000 个在 6.0 下至少报一个错；除 74 个外，7.0 也同样报错。那 74 个是已知未完成项（正则语法检查、isolatedDeclarations 报错）或有意变更。--incremental、project references、--build 模式已移植。

benchmark：

预览期限制：

• downlevel 编译实际只回退到 es2021，不能编译 decorator
• --watch 可能效率更低
• 不支持现有 Strada API，依赖它的工具需按上面的并存方案过渡