tsconfig配置详解

{
    // 编译器选项（核心配置）
    "compilerOptions": {
        "target": "ES2020",        // 编译目标 ECMAScript 版本
        /**
         * 指定生成的模块系统
         * CommonJS: Node.js
         * ESNext/ES2020: 现代浏览器/打包工具
         * AMD: RequireJS
         * UMD: 库开发
         */
        "module": "ES2020",   // 模块系统（commonjs 或 es6）
        /**
         * 包含的类型声明库
         *
         * // 没有 "DOM" 时
         * document.getElementById('app');  // ❌ 错误: 找不到 'document'
         * // 有 "DOM" 时
         * document.getElementById('app');  // ✅ 正确
         * // 没有 "ES2020" 时
         * const result = Promise.allSettled([]);  // ❌ 错误
         * // 有 "ES2020" 时
         * const result = Promise.allSettled([]);  // ✅ 正常
         */
        "lib": [
            "ES2020",
            "DOM"
        ],
        /**
         * 模块解析的基础目录
         * // 不用 baseUrl
         *  import { helper } from '../../../utils/helper';
         *  // 设置 baseUrl: "./src" 后
         *  import { helper } from 'utils/helper';
         */
        "baseUrl": "./src",
        /**
         * 指定源文件的根目录
         * 设置前 (rootDir 自动推断):
         * src/index.ts → dist/src/index.js  ❌ 多了一层
         * 设置后 (rootDir: "./src"):
         * src/index.ts → dist/index.js      ✅ 正确
         * 通常设置为项目的根目录（包含 src 目录）
         */
        "rootDir": "./src",
        /**
         * 编译输出目录
         * 编译后的文件将输出到该目录
         * 通常设置为 dist 目录
         */
        "outDir": "./dist",
        // 路径别名映射
        "paths": {
            "@/*": ["src/*"],
            "@components/*": ["src/components/*"]
        },
        /**
         * 模块解析策略: 
         * node - 符合 Node.js 模块解析规则
         * classic: 旧版 TS 解析（不推荐）
         * bundler: 现代打包工具（Vite/Webpack）
         * node16/nodenext: 支持 ESM 的 Node.js
         */
        "moduleResolution": "bundler", // 模块解析策略（node 或 classic）
        /**
         * 开启严格模式，启用所有严格类型检查（推荐开启）
         * 开启后，编译器会检查更多的类型错误和最佳实践
         * 等同于开启以下所有严格模式：
         * - noImplicitAny
         * - strictNullChecks
         * - strictFunctionTypes
         * - strictBindCallApply
         * - strictPropertyInitialization
         * - noImplicitThis
         * - alwaysStrict
         */
        "strict": true,         // 开启严格模式
        "strictNullChecks": true, // 开启严格的 null 检查
        "noImplicitAny": true,    // 禁止隐式的 any 类型
        "noUnusedLocals": true,   // 报告未使用的局部变量
        "noUnusedParameters": true, // 报告未使用的函数参数
        "noImplicitReturns": true,  // 报告函数没有显式返回值(return)
        "noFallthroughCasesInSwitch": true, // 报告 switch 语句中缺少 break 或 continue
        /**
         * 改善 ES 模块与 CommonJS 模块的互操作性
         * // 没有 esModuleInterop
        *   import * as express from 'express';  // 必须这样写
        *   const app = express();
        *   // 有 esModuleInterop
        *   import express from 'express';  // ✅ 可以这样写
        *   const app = express();
         */
        "esModuleInterop": true,
        /**
         * 允许从没有默认导出的模块默认导入，这个选项不会影响生成的代码，只会影响类型检查。
         * 报错：This module can only be referenced with ECMAScript imports/exports by turning on the 'allowSyntheticDefaultImports' flag and referencing its default export.
         * 
        */
        "allowSyntheticDefaultImports": true, // 允许从没有默认导出的模块默认导入
        "forceConsistentCasingInFileNames": true, // 强制文件名大小写一致
        /**
         * 生成对应的 .d.ts 声明文件
         * src/utils.ts → dist/utils.js + dist/utils.d.ts
         */
        "declaration": true,
        "declarationDir": "./dist", // 指定声明文件输出目录
        /**
         * 生成 .d.ts 映射文件，用于调试
         * 作用：在 IDE 中点击类型定义时，可以跳转到源 .ts 文件而不是 .d.ts
         */
        "declarationMap": true, // 生成 .d.ts 映射文件，用于调试
        /**
         * 只生成声明文件，不生成 JS 文件
         * 使用场景：使用其他工具（如 Babel）编译 JS，TypeScript 只负责类型检查
         */
        "emitDeclarationOnly": true,
        "resolveJsonModule": true, // 允许导入 JSON 文件
        /**
         * 每个文件作为独立模块，确保每个文件可以独立编译
         * 作用：避免在编译时引入全局变量污染
         * 使用场景：使用 Babel、esbuild 等单文件编译工具时必须开启
         * // ❌ 不允许: 只有类型的重新导出
         * export { SomeType } from './types';
         * // ✅ 允许
         * export type { SomeType } from './types';
         *
         * 报错提示：报错提示：'main.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.
         *
         */
        "isolatedModules": true, // 每个文件作为独立模块，确保每个文件可以独立编译
        "jsx": "react-jsx", // 开启 JSX 支持，指定 JSX 工厂函数为 React.createElement
        "noEmit": true, // 不输出编译结果, 使用场景：只用 TypeScript 做类型检查，编译交给其他工具
        "allowJs": true, // 允许编译 JS 文件
        "checkJs": true, // 检查 JS 文件中的类型错误
        /**
         * 生成 source map 文件，用于调试
         * 作用：在浏览器或 IDE 中调试时，能够映射到原始 TypeScript 代码
         * src/index.ts → dist/index.js + dist/index.js.map
         */
        "sourceMap": true, // 生成 source map 文件，用于调试
        "inlineSourceMap": true, // 将 source map 内联到 JS 文件中
        "inlineSources": true, // 将源代码内联到 source map 中
        "skipLibCheck": true, // 性能优化，跳过对 .d.ts 文件的类型检查
        "incremental": true, // 增量编译，只编译变更的文件,效果：生成 .tsbuildinfo 文件，下次编译只处理变更的文件
        "composite": true, // 开启项目引用（references）功能，用于大型项目的增量编译
    },
    "include": [],            // 指定需要编译的文件或目录模式
    "exclude": [],            // 排除不需要编译的文件（在 include 基础上排除）
    "files": [],              // 精确指定要编译的文件列表（不支持通配符）
    "extends": "",            // 继承另一个配置文件
    /**
    * 项目引用，用于大型项目的增量编译
    * 每个引用都是一个对象，包含 path 字段指定被引用项目的 tsconfig.json 文件路径
    * { "path": "./packages/client" } 引用 client 包下的 tsconfig.json 文件
    */
    "references": []
}