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默认truemodule默认esnexttarget默认esnext之前的那一个当前稳定 ECMAScript 版本noUncheckedSideEffectImports默认truelibReplacement默认falsestableTypeOrdering默认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或preservebaseUrl不再支持,paths改成相对于项目根esModuleInterop、allowSyntheticDefaultImports不能为falsealwaysStrict视为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属性赋值混用
升级顺序与自查
- 先在 6.0 下打开
stableTypeOrdering、清掉ignoreDeprecations,确保npx tsc --noEmit干净通过。 - 并行安装:7.0 的
tsc加上@typescript/typescript6提供的tsc6。 - 跑
npx tsc --noEmit,先处理选项级报错(被删的选项、不能为false的选项),再处理类型报错。 - 补
rootDir,把types从默认空数组改成显式列表。 - 检查
paths是否已改为相对项目根;grep 一遍asserts改成with。 - 有自研字符串工具类型的,用 emoji 输入验证推断结果。
- JS 项目按上面的 JSDoc 清单逐条改。
- 依赖 compiler 的构建插件,在 7.1 API 落地前继续用
tsc6那条路。 npx tsc --showConfig对比一下最终生效的配置,确认默认值符合预期。
链接
- 公告:
- CHANGES.md:
- 迁移实录(tsconfig 报错与修法):