上周有个读者跟我吐槽,说他接手的项目里,一行 import 报红,整组人查了仨小时,最后发现是 tsconfig.json 里 baseUrl 和 paths 配岔了。他问我:这玩意儿不就是个项目配置文件吗,怎么比代码本身还难搞?
这话问到点子上了。很多人学 TypeScript,语法啃得挺熟,可一到”从零搭一个项目”就懵——tsc --init 生成的那一百多行注释,密密麻麻像一份租房合同,你不签字(不配好),项目压根住不进去。
这篇文章我不讲语法,就把”项目搭建”这件事掰开揉碎:配置怎么选、坑在哪、以及 2026 年必须知道的大变化。
一、起点别走歪:脚手架选对了,省一半事
先说个最实在的建议:别从零手写配置,先让脚手架替你打底。
2026 年了,主流路径已经非常成熟。前端项目一行命令:
npm create vite@latest my-app -- --template react-ts
后端项目直接上 NestJS,它天生就是 TypeScript 写的,目录结构、装饰器、依赖注入全都替你安排好了。Vue 3 官方脚手架对 TS 的支持也不再是”能跑就行”,类型推断相当聪明。
你可能会问:脚手架生成的 tsconfig.json 就够了吗?不够,但它是好底子。你要做的是在它上面做两件事:收紧检查、补齐规范。
看上面这张目录图,src 下面按 api、components、hooks、types、utils 分门别类,外加根目录躺着的 tsconfig.json、.eslintrc.json、.prettierrc——这就是现代 TS 项目的标准长相。记住一个原则:目录结构是给人看的,配置文件是给机器看的,两者都得提前设计。
二、tsconfig:那几个真正影响命运的开关
tsc --init 生成的配置有上百个选项,但日常真正决定项目命运的,一只手数得过来。我把压箱底的推荐配置贴在这,再逐个说为什么:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"noEmitOnError": true
}
}
strict: true 是灵魂。 它一口气开启 noImplicitAny、strictNullChecks 等六组严格检查。我知道很多人嫌它烦——”undefined 不能随意赋值太束手束脚了”。但你换个角度想:它像个爱较真的质检员,今天它拦你三次,明天线上就少一个凌晨两点的报警电话。新项目不开严格模式,等于花 TS 的钱,干 JS 的活。
skipLibCheck: true 是大型项目的续命丹。 它让编译器跳过对 node_modules 里 .d.ts 声明文件的检查。项目一大,类型检查慢得离谱,八成是卡在这。开了它,编译速度肉眼可见地快。
noEmitOnError: true 防止带病出货。 类型都报错了还硬生成 JS 文件?那编译这一步就形同虚设。CI 流水线里尤其要加上。
这里还有个大坑要单独说:路径别名 @/components/xxx 看着优雅,但 baseUrl + paths 这套组合是新人报错重灾区——编辑器里跳转好好的,一编译就”找不到模块”。原因通常是忘了同步配置 ESLint 的 import/resolver,或者 paths 写的相对路径和 baseUrl 没对齐。2026 年的新趋势是干脆弃用 baseUrl,直接在 paths 里写相对项目根的路径,少一层间接,少一层错。
像上面这种满屏报红的场景,老前端都经历过。别慌,九成是类型声明没加载上——往下看我说的”types 陷阱”。
三、2026 年最大的坑:types: [] 和正在路上的 TS 7
这是这篇文章里最值钱的一段,请认真看。
TypeScript 6.0 之后,官方一口气改了好几个默认值,其中杀伤力最大的是 types 默认变成了空数组 []。以前编译器会自动把 node_modules/@types 下的包全拉进来,现在默认一个都不加载。于是大量老项目升级后会突然报这种错:
Cannot find name 'process'. Try adding 'node' to the types field in your tsconfig.
process 不认识、describe 不认识,全因为 @types/node、@types/jest 没显式声明。解法很简单,但必须你知道:
{
"compilerOptions": {
"types": ["node", "jest"]
}
}
同理,rootDir 的默认行为也变了,如果你的编译产物突然从 dist/index.js 变成 dist/src/index.js,就是它在搞鬼,显式写上 "rootDir": "./src" 即可。
更大的新闻是 TypeScript 7。微软用 Go 语言重写了编译器(内部代号 Corsa),实测一个 15 万行代码的项目,全量类型检查从 52 秒降到 5.3 秒,提速近 10 倍;编辑器里打开一个满是类型错误的文件,从 17.5 秒降到 1.3 秒。语言本身一个标点都没改,但”躯干”整个换掉了。
对你我意味着什么?两件事。其一,老配置里的历史包袱赶紧清——moduleResolution: node(老的 node10 写法)、target: es5、baseUrl 这些在 7.0 里都是硬错误,趁现在用 6.0 的迁移工具改掉。其二,如果你的项目还停在 5.x,路线是:先升 6.0 消化弃用警告,再在 CI 里并排跑一次 7.0 验证。好消息是官方保证语义兼容,这次升级大概率是你今年最无痛的一次大版本迁移。
四、别把 ESLint 和 Prettier 留到最后
我见过太多项目,跑起来一个月了才想起来加代码规范,结果一格式化,几百个文件全变 diff,代码评审直接变灾难现场。
正确姿势是第一天就装上:
npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier
现在的生态里,typescript-eslint 已经是标配,规则覆盖 TS 特有的坏味道——比如禁止没意义的 as any。配合 VS Code 的 ESLint 插件设置保存自动修复,你根本不用操心格式问题。
特别说一条团队规范:把 any 当违规处理,用 unknown + 类型守卫替代。any 就像把门锁拆了图进出方便,短期爽,长期等于开着门睡觉。类型检查拦不住 any,等于 TS 白装。
调试这块也有个省事方案:装个 ts-node,npx ts-node src/index.ts 直接跑 TS 文件,配合 VS Code 的 launch.json 还能断点单步,不用手动盯着编译产物。
写在最后
TypeScript 圈子里有句话我挺认同:类型即文档,类型即测试。项目搭建这件事,本质上就是在一开始花两小时立好规矩,换后面几个月的清净。
配置文件烦吗?烦。但你想,把规矩立在编译阶段,总比把坑埋在运行阶段要强——前者是红色波浪线,后者是 P0 故障单。
你的项目 tsconfig 里开过 strict 吗?升级 6.0/7.0 踩过什么坑?评论区聊聊,我挨个回。
