tsconfig.json 是 TypeScript 项目的核心配置文件 ，用于控制编译行为、类型检查规则、模块解析策略、文件包含/排除范围等。下面为你提供一份 完整、系统、实用的 tsconfig.json 使用指南，包括：
- 配置结构说明
- 常用字段详解
- 不同场景（通用项目、Vue + TS、库开发）的配置示例
- 最佳实践建议
一、基本结构
一个典型的 tsconfig.json 结构如下：
{
"compilerOptions": {
// 编译选项（最重要）
},
"include": [], // 包含哪些文件
"exclude": [], // 排除哪些文件
"files": [], // 显式指定文件（优先级高于 include）
"extends": "", // 继承其他配置
"references": [] // 项目引用（monorepo）
}⚠️ 注意：只要目录中存在 tsconfig.json，TypeScript 就认为这是项目根目录。
二、核心字段详解
1. compilerOptions（编译选项）
基础设置
| 配置项 | 说明 | 推荐值 |
|---|---|---|
target |
编译成哪个 JS 版本（ES5/ES2015/ES2020/ESNext） | "ES2020" 或 "ESNext" |
module |
模块系统（CommonJS/ESNext/AMD 等） | "ESNext"（现代前端）或 "CommonJS"（Node.js） |
moduleResolution |
模块解析策略 | "Node"（兼容 npm） |
outDir |
输出目录 | "./dist" |
rootDir |
源码根目录 | "./src" |
sourceMap |
生成 .map 文件便于调试 |
true |
declaration |
生成 .d.ts 声明文件 |
true（库开发需要） |
removeComments |
移除注释 | false（开发时保留） |
严格类型检查（强烈建议开启）
| 配置项 | 作用 |
|---|---|
strict |
启用所有严格检查（相当于开启下面所有）✅ |
noImplicitAny |
禁止隐式 any |
strictNullChecks |
严格 null/undefined 检查 |
strictFunctionTypes |
严格函数参数检查 |
noImplicitThis |
禁止隐式 this 类型 |
alwaysStrict |
自动添加 "use strict" |
兼容性 & 工程化
| 配置项 | 说明 |
|---|---|
esModuleInterop |
允许 import React from 'react'（兼容 CommonJS）✅ |
allowSyntheticDefaultImports |
允许从无默认导出的模块默认导入（配合 esModuleInterop） |
resolveJsonModule |
支持 import data from './data.json' |
skipLibCheck |
跳过 node_modules/@types 的类型检查（提升速度）✅ |
forceConsistentCasingInFileNames |
强制文件名大小写一致（避免跨平台问题）✅ |
allowJs |
是否编译 .js 文件（混合项目） |
checkJs |
在 .js 中报告类型错误（需 allowJs: true） |
高级优化
| 配置项 | 说明 |
|---|---|
incremental |
启用增量编译（大幅提升二次构建速度）✅ |
tsBuildInfoFile |
增量编译缓存文件路径（如 "./dist/.tsbuildinfo"） |
isolatedModules |
强制每个文件可独立编译（与 Babel/Vite 兼容）✅ |
verbatimModuleSyntax |
替代 importsNotUsedAsValues，更清晰控制 import 类型（TS 5.0+）✅ |
2. include / exclude / files
-
include: Glob 模式，包含要编译的文件（默认：["**/*"]）"include": ["src//*", "types//*.d.ts"]
-
exclude: 排除文件（默认排除node_modules,bower_components,jspm_packages,outDir）"exclude": ["node_modules", "dist", "coverage"]
-
files: 显式列出文件（一旦使用，include只对依赖生效）
✅ Vue 项目通常需包含 .vue 文件：
3. extends
继承其他配置，避免重复：
{
"extends": "@vue/tsconfig/tsconfig.dom.json",
"compilerOptions": {
// 覆盖或补充配置
}
}常用继承源：
@vue/tsconfig（Vue 官方）tsconfig/base.json（自建基础配置）
三、典型配置示例
✅ 示例 1：通用前端项目（Vite + TS）
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Node",
"strict": true,
"jsx": "preserve",
"sourceMap": true,
"resolveJsonModule": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
},
"types": ["vite/client", "node"],
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"noEmit": true
},
"include": [
"src/**/*.ts",
"src/**/*.d.ts",
"src/**/*.tsx",
"src/**/*.vue"
],
"exclude": ["node_modules", "dist"]
}💡 noEmit: true 表示只做类型检查，不输出 JS（由 Vite/Bundler 负责编译）
✅ 示例 2：Node.js 后端项目
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"sourceMap": true,
"declaration": false,
"incremental": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}✅ 示例 3：发布 NPM 包（带声明文件）
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "Node",
"outDir": "./dist",
"declaration": true,
"declarationDir": "./dist/types",
"declarationMap": true,
"sourceMap": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}四、最佳实践建议
- **始终开启 **
strict: true------ 提升代码健壮性。 - **使用
include而非 **files------ 更灵活。 - **前端项目设 **
noEmit: true------ 交由构建工具处理。 - **启用 **
incremental------ 加快本地开发编译速度。 - **Vue 项目继承 **
@vue/tsconfig------ 避免踩坑。 - **不要手动维护 **
lib------ 除非有特殊需求（如 Web Worker）。 - 使用
paths简化 import 路径（配合构建工具 alias）。
五、如何生成初始配置？
在项目根目录运行：
npx tsc --init会生成带详细注释的默认配置，按需