tsconfig.json 编译选项与配置模板
最后更新：2026-10-22
tsconfig.json 编译选项与配置模板
tsconfig.json 是 TypeScript 项目的"总开关"文件：放在项目根目录，告诉编译器（tsc）编译哪些文件、编译成什么样。其中 strict 是最重要的一个开关——一键打开严格全家桶（strictNullChecks、noImplicitAny 等），能在编译期抓住绝大多数空值和类型隐患。
| 分组 | 工程与实战 |
|---|---|
| 类型 | 配置 |
| 严格模式 | 不需要 |
ℹ️ 说明 编辑器将 TypeScript 转译为 JavaScript 后运行（不做类型检查）；类型检查结果见示例 Output。
📝 语法
// tsconfig.json（最小严格配置）
{
"compilerOptions": {
"target": "ES2020", // 产物 JS 的语言版本
"module": "commonjs", // 模块格式（Node 常用 commonjs，打包器常用 ESNext）
"outDir": "./dist", // 产物输出目录
"rootDir": "./src", // 源码根目录
"paths": { "@utils/*": ["./src/utils/*"] }, // 模块路径别名
"strict": true // 一键打开严格检查全家桶
},
"include": ["src"] // 只编译 src 下的文件
}⚙️ 参数
| strict | 严格检查总开关：同时启用 strictNullChecks、noImplicitAny、strictFunctionTypes 等；新项目建议无脑开启 |
|---|---|
| target / module | target 决定产物 JS 的语言版本（可用的内置类型随之变化）；module 决定产物用什么模块格式 |
| outDir / rootDir / paths | 产物目录 / 源码根目录 / 路径别名。paths 只是编译期的名字映射，运行时解析仍需打包器或 Node 子域配置配合 |
返回值：无返回值——tsconfig.json 是配置文件，只作用于编译期，本身不参与运行。
▶ 示例
修改下面的代码，点击试一试查看转译运行结果：
输出：
length = 5
sum = 5
（转译后运行输出；类型检查由 tsc 完成——删掉 ?? 兜底会得到 error TS18047，给 sum 的参数去掉类型注解会得到 error TS7006）💡 要点
ℹ️ 说明 strict 不是单个检查，而是一组检查的集合开关：strictNullChecks、noImplicitAny、strictFunctionTypes、strictBindCallApply、strictPropertyInitialization、useUnknownInCatchVariables 等。
💡 提示 新项目可用 tsc --init 生成模板再精简；paths 路径别名要与打包器（Vite/webpack 的 alias）同步配置，否则编译通过、运行时找不到模块。
⚠️ 注意 存量项目不必硬上 strict：可先开 strictNullChecks 单项渐进修复，全部干净后再打开整个 strict，避免一次出现成百上千个报错。
🏷️ 相关工程与实战
💡 相关案例
更多案例即将上线。
📚 相关教程
❓ 常见问题
Q strict: true 到底打开了哪些检查？
A 它是一组检查的集合开关：strictNullChecks（null/undefined 必须显式处理）、noImplicitAny（禁止隐式 any）、strictFunctionTypes（函数参数逆变检查）、strictPropertyInitialization（类属性必须初始化）、useUnknownInCatchVariables（catch 变量是 unknown）等。可单独关闭其中一项做渐进迁移。
Q target 和 module 有什么区别？
A target 决定把新语法降到哪个 JS 版本（如 ES2020 支持可选链）；module 决定产物用什么模块系统（commonjs / ESNext / node16）。前者管语言特性，后者管 import/export 被编译成什么形式。
Q paths 路径别名配置后运行时找不到模块怎么办？
A paths 只是给编译器看的名字映射，转译产物里别名会原样保留。需要运行时也认识它：打包器项目配 Vite/webpack 的 resolve.alias；纯 Node 项目用 package.json 的 imports 字段或 tsconfig-paths 这类运行时补丁。
