一、 tsconfig.json 示例
{
"compilerOptions": {
// 1. 编译目标与模块系统
"target": "ES2020", // 指定编译后的 JavaScript 版本为 ES2020
"module": "ESNext", // 指定模块系统为 ESNext（支持动态导入等）
"moduleResolution": "node", // 模块解析策略为 Node.js 风格（兼容 npm 包）
// 2. 严格类型检查
"strict": true, // 启用所有严格类型检查选项
"noImplicitAny": true, // 禁止隐式 any 类型（严格模式默认启用）
"strictNullChecks": true, // 强制 null/undefined 检查，避免运行时错误
"strictFunctionTypes": true, // 启用严格的函数类型检查
"strictBindCallApply": true, // 启用严格的 bind/call/apply 检查
"strictPropertyInitialization": true, // 启用严格的属性初始化检查（需配合类构造器）
"noImplicitThis": true, // 禁止隐式的 this 类型（必须显式声明）
"alwaysStrict": true, // 在生成的代码中启用严格模式
// 3. 路径映射与根目录
"baseUrl": "./", // 基础路径（相对于 tsconfig.json）
"paths": {
"@/*": ["src/*"], // 将 @/ 映射到 src/，简化 import 路径
"@components/*": ["src/components/*"], // 将 @components/ 映射到 src/components/
"@utils/*": ["src/utils/*"] // 将 @utils/ 映射到 src/utils/
},
"rootDir": "src", // 源码根目录（编译时从 src 开始）
"outDir": "dist", // 输出目录（编译后的文件）
// 4. 开发体验优化
"sourceMap": true, // 生成 sourceMap 文件，便于调试
"inlineSources": false, // 是否将源码嵌入到 sourceMap 中（默认 false）
"incremental": true, // 启用增量编译，缓存提升速度
"tsBuildInfoFile": "./.cache/tsbuildinfo", // 增量编译信息存储文件
// 5. JavaScript 兼容性
"allowJs": true, // 允许编译 .js 文件（适用于渐进式迁移到 TypeScript）
"checkJs": false, // 不检查 .js 文件（默认 false，可设为 true 启用）
"maxNodeModuleJsDepth": 1, // 限制解析 node_modules 中 .js 文件的深度（默认 1）
// 6. 库与类型声明
"skipLibCheck": true, // 跳过第三方库的类型检查，提高编译速度
"declaration": true, // 生成 .d.ts 声明文件，便于库发布
"emitDeclarationOnly": false, // 是否仅生成声明文件（不编译 JS，默认 false）
"declarationMap": true, // 生成声明文件的 sourceMap，便于调试类型
// 7. 其他实用选项
"jsx": "react-jsx", // React 的 JSX 转换（Vite/Next.js 兼容）
"esModuleInterop": true, // 解决 CommonJS 与 ES 模块的导入问题
"forceConsistentCasingInFileNames": true, // 强制文件名大小写一致（跨平台安全）
"preserveSymlinks": false, // 是否保留符号链接（默认 false）
"resolveJsonModule": true, // 允许导入 .json 文件
"isolatedModules": false, // 是否将每个文件作为独立模块（默认 false，适用于 Babel 等）
// 8. 实验性功能（谨慎使用）
"experimentalDecorators": true, // 启用实验性装饰器（需配合 @babel/plugin-proposal-decorators）
"emitDecoratorMetadata": true, // 启用装饰器元数据反射（需配合 experimentalDecorators）
// 9. 类型导入与库设置
"types": ["node", "jest"], // 自动导入的类型声明文件（如 node、jest）
"typeRoots": ["./node_modules/@types", "./types"], // 类型声明文件的根目录
"lib": ["ES2020", "DOM", "DOM.Iterable"] // 编译时需要包含的库文件
},
// 10. 文件控制
"include": [
"src/**/*.ts", // 包含 src 下的所有 .ts 文件
"src/**/*.tsx", // 包含 src 下的所有 .tsx 文件
"src/**/*.d.ts" // 包含 src 下的所有 .d.ts 文件
],
"exclude": [
"node_modules", // 排除 node_modules 目录
"dist", // 排除 dist 目录
"tests/**/*.spec.ts", // 排除测试文件
"**/*.test.ts" // 排除所有 .test.ts 文件
],
// 11. 高级场景（可选）
// "files": ["src/index.ts"], // 指定白名单文件（不推荐，通常用 include）
// "extends": "./base-config.json" // 继承其他配置文件（Monorepo 常用）
"references": [] // 引用其他项目（适用于 Monorepo 中的项目引用）
}二、配置项说明
1、编译目标与模块系统
指定编译后的 JavaScript 版本和模块系统，兼容现代浏览器和打包工具。
2、严格类型检查
启用严格类型检查，避免运行时错误，提高代码质量。
3、路径映射与根目录
简化导入路径，提高代码可读性。
4、开发体验优化
生成 sourceMap 和增量编译信息，提升调试和编译速度。
5、JavaScript 兼容性
支持渐进式迁移到 TypeScript，兼容现有 JavaScript 代码。
6、库与类型声明
生成类型声明文件，便于库发布和类型检查。
7、其他实用选项
解决 CommonJS 与 ES 模块的导入问题，强制文件名大小写一致等。
8、实验性功能
启用装饰器等实验性功能（需配合 Babel 等工具）。
9、类型导入与库设置
自动导入类型声明文件，指定编译时需要的库文件。
10、文件控制
精确控制包含和排除的文件，避免不必要的编译。
11、高级场景
支持 Monorepo 中的项目引用和配置继承。
12、适用场景
现代前端项目（React/Vue/Vite）。
需要严格类型检查和开发效率优化的场景。
大型项目或 Monorepo 结构。
通过以上配置，可以兼顾类型安全、开发体验和编译性能。