0248. 常用编译配置组合
1. 🎯 本节内容
- Node.js 项目配置
- React/Vue 前端配置
- 库项目配置
- Monorepo 配置
- 全栈项目配置
- 配置选择建议
2. 🫧 评价
不同类型项目需要不同的 TypeScript 配置，本节提供常见场景的最佳实践配置模板。
- 开箱即用的配置模板
- 针对不同项目类型优化
- 包含开发和生产环境
- 遵循社区最佳实践
- 可直接复制使用
- 节省配置时间
3. 🤔 Node.js 项目配置？
3.1. 基础 Node.js 项目
json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"resolveJsonModule": true,
"sourceMap": true,
"declaration": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
3.2. Node.js + TypeScript 最新版
json
{
"compilerOptions": {
"target": "ES2022",
"module": "node16",
"lib": ["ES2022"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node16",
"resolveJsonModule": true,
"allowSyntheticDefaultImports": true,
"sourceMap": true,
"declaration": true,
"declarationMap": true,
"incremental": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.spec.ts"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
3.3. Express 应用
json
{
"extends": "@tsconfig/node16/tsconfig.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"sourceMap": true,
"incremental": true,
"types": ["node", "express"]
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
4. 🤔 前端项目配置？
4.1. React 项目
json
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"jsx": "react-jsx",
"module": "esnext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"allowSyntheticDefaultImports": true,
"types": ["vite/client"]
},
"include": ["src"],
"references": [{ "path": "./tsconfig.node.json" }]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
4.2. Vue 3 项目
json
{
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "preserve",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
"references": [{ "path": "./tsconfig.node.json" }]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
4.3. Next.js 项目
json
{
"compilerOptions": {
"target": "ES2017",
"lib": ["DOM", "DOM.Iterable", "ESNext"],
"allowJs": true,
"skipLibCheck": true,
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"module": "esnext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"incremental": true,
"plugins": [
{
"name": "next"
}
],
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
"exclude": ["node_modules"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
5. 🤔 库项目配置？
5.1. 通用库配置
json
{
"compilerOptions": {
"target": "ES2015",
"module": "esnext",
"lib": ["ES2015"],
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
5.2. 多格式输出（ESM + CJS）
json
// tsconfig.json（基础配置）
{
"compilerOptions": {
"target": "ES2015",
"strict": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
// tsconfig.esm.json（ESM 构建）
{
"extends": "./tsconfig.json",
"compilerOptions": {
"module": "esnext",
"outDir": "./dist/esm"
}
}
// tsconfig.cjs.json（CommonJS 构建）
{
"extends": "./tsconfig.json",
"compilerOptions": {
"module": "commonjs",
"outDir": "./dist/cjs"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
json
// package.json
{
"name": "my-library",
"main": "./dist/cjs/index.js",
"module": "./dist/esm/index.js",
"types": "./dist/esm/index.d.ts",
"exports": {
".": {
"import": "./dist/esm/index.js",
"require": "./dist/cjs/index.js",
"types": "./dist/esm/index.d.ts"
}
},
"scripts": {
"build": "npm run build:esm && npm run build:cjs",
"build:esm": "tsc -p tsconfig.esm.json",
"build:cjs": "tsc -p tsconfig.cjs.json"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
6. 🤔 Monorepo 配置？
6.1. Monorepo 根配置
json
// tsconfig.base.json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"moduleResolution": "node",
"resolveJsonModule": true,
"composite": true
}
}
// tsconfig.json
{
"files": [],
"references": [
{ "path": "./packages/core" },
{ "path": "./packages/utils" },
{ "path": "./packages/app" }
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
6.2. 子包配置
json
// packages/core/tsconfig.json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
// packages/app/tsconfig.json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"references": [
{ "path": "../core" },
{ "path": "../utils" }
],
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
7. 🤔 如何选择合适的配置？
7.1. 根据项目类型选择
text
Node.js 服务器：
- target: ES2020
- module: commonjs 或 node16
- lib: ES2020
浏览器应用：
- target: ES2020
- module: esnext
- lib: ES2020, DOM, DOM.Iterable
- jsx: react-jsx 或 preserve
库项目：
- target: ES2015（更广兼容性）
- declaration: true
- 多格式输出
Monorepo：
- composite: true
- references: [...]
- 继承基础配置1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
7.2. 开发 vs. 生产
json
// tsconfig.json（开发）
{
"compilerOptions": {
"sourceMap": true,
"incremental": true,
"noEmit": false
}
}
// tsconfig.prod.json（生产）
{
"extends": "./tsconfig.json",
"compilerOptions": {
"sourceMap": false,
"removeComments": true,
"declaration": true
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
7.3. 严格程度
json
// 宽松（快速开发）
{
"compilerOptions": {
"strict": false,
"noImplicitAny": false,
"skipLibCheck": true
}
}
// 标准（推荐）
{
"compilerOptions": {
"strict": true,
"skipLibCheck": true
}
}
// 严格（高质量）
{
"compilerOptions": {
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
7.4. 使用预设配置
bash
# 安装预设
npm install --save-dev @tsconfig/node16
npm install --save-dev @tsconfig/react-native
npm install --save-dev @tsconfig/recommended1
2
3
4
2
3
4
json
{
"extends": "@tsconfig/node16/tsconfig.json",
"compilerOptions": {
"outDir": "./dist"
}
}1
2
3
4
5
6
2
3
4
5
6
7.5. 迁移策略
text
阶段 1：基础配置
- 启用 TypeScript
- 关闭严格检查
- allowJs: true
阶段 2：逐步严格
- 启用 noImplicitAny
- 启用 strictNullChecks
- 修复错误
阶段 3：完全严格
- strict: true
- 启用所有检查
- 代码质量最佳1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14