编程 TypeScript 7.0 升级笔记:真正卡住你的是 tsconfig 默认值和被删的编译选项

2026-11-19 21:08:21

TypeScript 7.0 升级笔记:真正卡住你的是 tsconfig 默认值和被删的编译选项

TypeScript 7.0 于 2026-07-08 发布(公告),是 Go 写的原生移植版本,结构、逻辑与原实现一一对应,靠原生代码速度和共享内存多线程,全量构建常见 8–12 倍提速。安装方式没变:

npm install -D typescript

下面是升级时实际会卡住的地方,集中在 tsconfig 和工具链。

与 6.0 的关系,以及并行安装

7.0 的兼容目标是:在 6.0 下能干净编译的项目(stableTypeOrdering 打开、不用 ignoreDeprecations),在 7.0 下编译结果应当一致。7.0 沿用 6.0 的新默认值,并且对 6.0 里标记为废弃的选项和写法直接硬报错,不再只是警告。

7.0 不带 API,新的 API 预期在 7.1 提供。兼容包 @typescript/typescript6 提供一个叫 tsc6 的可执行文件,因此 7.0 自带的 tsc 可以和它并存、不冲突;这个包同时重新导出了 6.0 的 API。typescript-eslint 这类工具是通过 peer dependency 从 typescript 导入的,所以推荐用 npm alias 安装:

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

默认值变了

  • strict 默认 true
  • module 默认 esnext
  • target 默认 esnext 之前的那一个当前稳定 ECMAScript 版本
  • noUncheckedSideEffectImports 默认 true
  • libReplacement 默认 false
  • stableTypeOrdering 默认 true,且不能关闭

rootDir 现在默认是 ./。tsconfig 在仓库根、源码在 src 的项目必须显式写:

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

types 现在默认是 []。以前会自动加载 node_modules/@types 下的全部包,装了 @types/chrome 也会静默生效;现在必须显式列出,否则会冒出一片 implicit any。想恢复旧行为写 ["*"],正常写法是按需列:

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

直接变硬报错的选项

  • target: es5 不再支持
  • downlevelIteration 不再支持
  • moduleResolution 的 node、node10 不再支持,推荐 nodenext / bundler;classic 也不再支持
  • module 的 amd、umd、systemjs、none 不再支持,推荐 esnext 或 preserve
  • baseUrl 不再支持,paths 改成相对于项目根
  • esModuleInterop、allowSyntheticDefaultImports 不能为 false
  • alwaysStrict 视为 true,不能为 false

另外几条容易漏的:namespace 声明里不能用 module 关键字;import 上的 asserts 关键字必须改成 with;skipDefaultLibCheck 下 /// 指令不再生效;当前目录存在 tsconfig.json 时,命令行构建不能直接传文件路径,除非加 --ignoreConfig。

模板字面量类型按 Unicode 码点推断

type HeadTail = S extends `${infer Head}${infer Tail}` ? [Head, Tail] : never;
type Result = HeadTail; // 7.0: ["😀", "abc"],之前是 ["\ud83d", "\ude00abc"]

自己实现过字符串 Length 之类工具类型的要重点看这条:以前按 UTF-16 码元建模,现在按码点,行为与 for...of、[...str] 一致。

JS 支持收窄

JSDoc 侧的变化:

  • 值不能当类型用,要写 typeof
  • @enum 不再被特殊识别,改用 @typedef 配合 (typeof E)[keyof typeof E]
  • 独立的 ? 不再是类型,用 any
  • @class 不会让函数变成构造器
  • 不支持后缀 !
  • 类型名必须写在 @typedef 标签内
  • Closure 风格的函数类型语法移除

对 this 起别名、重新赋值函数 prototype 也不再做特殊处理。

工具链的现实情况

除了没有 API 这件事,直接 import compiler 的插件(webpack loader 之类)会碰到兼容问题,需要等 7.1 或其适配版本。typescript-eslint、Volar 这类嵌入 TypeScript 的工具目前仍依赖 6.0,用上面的 tsc6 或 npm alias 走并行安装。

CHANGES.md 里的其他差异

  • node 位置改用 UTF8 偏移,非 ASCII 文件里的位置数值比以前大
  • skipLibCheck 下冲突声明会在所有相关位置报错,一些以前被完全压住的项目会在非 .d.ts 文件里看到声明冲突
  • "strict": false 时,参数类型为 undefined / unknown / any 的实参不能省略(void 仍可省略)
  • JSDoc 变参类型只是数组类型的同义词,不再让参数变成 rest 参数
  • strictNullChecks 关闭时,后缀 = 不再补 undefined
  • @param 标签最多作用于一个函数
  • 构造器函数(往 this / prototype 上挂东西)不再支持,改用 class
  • CommonJS 模块不能把 module.exports 赋值和 module.exports.xxx 属性赋值混用

升级顺序与自查

  1. 先在 6.0 下打开 stableTypeOrdering、清掉 ignoreDeprecations,确保 npx tsc --noEmit 干净通过。
  2. 并行安装:7.0 的 tsc 加上 @typescript/typescript6 提供的 tsc6。
  3. 跑 npx tsc --noEmit,先处理选项级报错(被删的选项、不能为 false 的选项),再处理类型报错。
  4. 补 rootDir,把 types 从默认空数组改成显式列表。
  5. 检查 paths 是否已改为相对项目根;grep 一遍 asserts 改成 with。
  6. 有自研字符串工具类型的,用 emoji 输入验证推断结果。
  7. JS 项目按上面的 JSDoc 清单逐条改。
  8. 依赖 compiler 的构建插件,在 7.1 API 落地前继续用 tsc6 那条路。
  9. npx tsc --showConfig 对比一下最终生效的配置,确认默认值符合预期。

链接

  • 公告:
  • CHANGES.md:
  • 迁移实录(tsconfig 报错与修法):
复制全文 生成海报 typescript 前端 编译 升级

推荐文章

程序员茄子在线接单