# 生成带全注释的默认配置（新手推荐）即生成默认配置文件
tsc --init
 
# 生成极简配置（仅保留核心项）
tsc --init --minimal

生成的默认配置示例：

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "strict": true,
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

{
  "compilerOptions": {
    // 编译选项（最重要）
  },
  "include": [],        // 包含哪些文件
  "exclude": [],        // 排除哪些文件
  "files": [],          // 显式指定文件（优先级高于 include）
  "extends": "",        // 继承其他配置
  "compileOnSave": true,// compileOnSave的值是true或false，如果设为true，在我们编辑了项目中的文件保存的时候，编辑器会根据tsconfig.json中的配置重新生成文件，不过这个要编辑器支持
  "references": []      // 项目引用（monorepo）
}

{
  /* ========================== 核心编译配置 ========================== */
  "compilerOptions": {
    /* -------------------------- 基础编译目标 -------------------------- */
    // 编译后的 JavaScript 版本（企业推荐 ES2020，兼容 Chrome 80+/Node.js 14+）
    "target": "ES2020",
    // 模块系统类型：前端用 ESNext（配合 Vite/Webpack），Node 用 CommonJS
    "module": "ESNext",
    // 指定编译器需要包含的内置库（DOM 适配浏览器，ESNext 包含最新语法）
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    // JSX 编译模式：React 17+ 用 react-jsx，Vue 用 preserve，React 16 用 react
    "jsx": "react-jsx",
    // 模块解析策略：Bundler 适配 Vite/Webpack，Node 适配 Node.js 运行时
    "moduleResolution": "Bundler",
    // 启用 ES 模块与 CommonJS 模块互操作（解决 import React from 'react' 报错）
    "esModuleInterop": true,
    // 允许合成默认导入（即使模块没有默认导出也能 import xxx from 'xxx'）
    "allowSyntheticDefaultImports": true,
    // 强制文件名大小写一致（避免 Windows/Linux 跨平台问题）
    "forceConsistentCasingInFileNames": true,
    // 允许导入 JSON 文件（如 import pkg from './package.json'）
    "resolveJsonModule": true,
    // 强制每个文件作为独立模块编译（适配打包工具，避免全局变量污染）
    "isolatedModules": true,
 
    /* -------------------------- 严格类型检查 -------------------------- */
    // 开启所有严格类型检查（企业级项目必须开启，是类型安全的核心）
    "strict": true,
    // 禁止隐式 any 类型（所有变量/参数必须显式指定类型）
    "noImplicitAny": true,
    // 严格的 null/undefined 检查（必须显式判断，杜绝 "cannot read property of undefined"）
    "strictNullChecks": true,
    // 严格的函数类型检查（防止参数/返回值类型不匹配）
    "strictFunctionTypes": true,
    // 严格检查 bind/call/apply 的参数类型（避免传参错误）
    "strictBindCallApply": true,
    // 强制类属性初始化（防止未初始化的属性导致运行时错误）
    "strictPropertyInitialization": true,
    // 禁止隐式 this 类型（this 必须有明确的类型声明）
    "noImplicitThis": true,
    // catch 语句的变量默认类型为 unknown（需显式类型收窄，更安全）
    "useUnknownInCatchVariables": true,
 
    /* -------------------------- 代码质量校验 -------------------------- */
    // 禁止未使用的局部变量（减少死代码，提升代码整洁度）
    "noUnusedLocals": true,
    // 禁止未使用的函数参数（规范函数定义，避免参数冗余）
    "noUnusedParameters": true,
    // 强制函数所有分支都有返回值（避免隐式 undefined 返回）
    "noImplicitReturns": true,
    // 禁止 switch 语句的 case 穿透（必须写 break/return，避免逻辑错误）
    "noFallthroughCasesInSwitch": true,
    // 禁止未检查的索引访问（如 arr[0] 需先判断数组长度，obj.key 需先判断 key 存在）
    "noUncheckedIndexedAccess": true,
    // 强制重写方法时添加 override 关键字（明确标识重写，提升可读性）
    "noImplicitOverride": true,
    // 禁止通过索引签名访问属性（必须用 obj.key 而非 obj['key']，提升类型安全）
    "noPropertyAccessFromIndexSignature": true,
 
    /* -------------------------- 路径别名配置 -------------------------- */
    // 模块解析的基础路径（配合 paths 使用）
    "baseUrl": "./",
    // 路径别名（解决长相对路径问题，如 ../../components → @/components）
    "paths": {
      "@/*": ["src/*"],                // 核心别名：@ 指向 src 根目录
      "@/components/*": ["src/components/*"], // 组件目录别名
      "@/utils/*": ["src/utils/*"],    // 工具函数目录别名
      "@/api/*": ["src/api/*"],        // 接口请求目录别名
      "@/types/*": ["src/types/*"]     // 类型声明目录别名
    },
 
    /* -------------------------- 类型声明配置 -------------------------- */
    // 类型声明文件的根目录（默认 node_modules/@types，扩展自定义类型目录）
    "typeRoots": ["./node_modules/@types", "./src/types"],
    // 指定需要加载的类型声明包（如 node/vite/client/jest）
    "types": ["node", "vite/client"],
    // 禁止从 UMD 模块中访问全局变量（避免全局污染）
    "allowUmdGlobalAccess": false,
 
    /* -------------------------- 编译输出控制 -------------------------- */
    // 编译产物输出目录
    "outDir": "./dist",
    // 源码根目录（保证输出目录结构与源码一致）
    "rootDir": "./src",
    // 生成类型声明文件（.d.ts），组件库/工具库必须开启
    "declaration": true,
    // 类型声明文件的输出目录
    "declarationDir": "./dist/types",
    // 生成类型声明映射文件（方便调试类型）
    "declarationMap": true,
    // 生成 sourceMap 文件（方便调试编译后的代码）
    "sourceMap": true,
    // 将源码内联到 sourceMap 中（生产环境更友好）
    "inlineSources": true,
    // 仅生成类型声明文件，不生成 JS 文件（组件库常用）
    "emitDeclarationOnly": false,
    // 不生成编译产物（仅做类型检查，前端项目配合打包工具使用）
    "noEmit": false,
    // 编译出错时不生成产物（避免错误代码上线）
    "noEmitOnError": true,
 
    /* -------------------------- 性能优化配置 -------------------------- */
    // 启用增量编译（只编译变更的文件，大型项目编译速度提升 50%+）
    "incremental": true,
    // 增量编译的缓存文件路径（放在 node_modules 缓存目录，避免提交到仓库）
    "tsBuildInfoFile": "./node_modules/.cache/tsbuildinfo",
    // 跳过第三方库的类型检查（提升编译速度，避免第三方库类型错误影响项目）
    "skipLibCheck": true,
    // 跳过 TypeScript 内置库的类型检查（进一步提升编译速度）
    "skipDefaultLibCheck": true,
    // 解除编译器的内存大小限制（大型项目避免内存溢出）
    "disableSizeLimit": true,
 
    /* -------------------------- 高级特性配置 -------------------------- */
    // 启用实验性装饰器（Angular/NestJS 常用，普通项目建议关闭）
    "experimentalDecorators": false,
    // 发射装饰器元数据（配合 experimentalDecorators 使用）
    "emitDecoratorMetadata": false,
    // 使用 ES 标准的类字段定义（兼容最新的类语法）
    "useDefineForClassFields": true,
    // 保留 const enum 定义（避免编译后枚举被内联，方便外部使用）
    "preserveConstEnums": true,
    // 不删除代码注释（保留注释便于调试，生产环境可开启）
    "removeComments": false,
    // 允许编译 JS 文件（混合 TS/JS 项目开启）
    "allowJs": false,
    // 检查 JS 文件的类型错误（混合项目开启，纯 TS 项目关闭）
    "checkJs": false
  },
 
  /* ========================== 编译范围控制 ========================== */
  // 需要编译的文件/目录（支持 glob 通配符：* 匹配文件，** 匹配子目录）
  "include": [
    "src/**/*",               // 编译 src 下所有文件（包括子目录）
    "src/**/*.json",          // 编译 src 下的 JSON 文件
    "vite.config.ts",         // 编译构建配置文件
    "build/**/*"              // 编译构建脚本
  ],
  // 排除编译的文件/目录（优先级高于 include）
  "exclude": [
    "node_modules",           // 排除依赖目录（无需编译）
    "dist",                   // 排除输出目录（避免循环编译）
    "build",                  // 排除构建产物目录
    "**/*.test.ts",           // 排除测试文件（由 Jest/Vitest 单独处理）
    "**/*.spec.ts",           // 排除测试规范文件
    "**/*.mock.ts",           // 排除 Mock 文件
    "**/*.stories.tsx"        // 排除组件文档文件
  ],
 
  /* ========================== 配置继承（Monorepo 必备） ========================== */
  // 继承基础配置文件（提取通用配置，避免重复）
  "extends": "./tsconfig.base.json",
 
  /* ========================== 项目引用（多包依赖） ========================== */
  // 引用其他子项目（Monorepo 中实现项目间依赖管理）
  "references": [
    { "path": "../common" },  // 引用 common 子项目
    { "path": "../utils" }    // 引用 utils 子项目
  ]
}

"noImplicitAny": true, // 禁止隐式 any 类型
// 错误示例（开启后报错）：
// function add(a, b) { return a + b; } // a/b 隐式为 any
// 正确示例：
// function add(a: number, b: number): number { return a + b; }

"strictNullChecks": true, // 严格 null/undefined 检查
// 错误示例（开启后报错）：
// const name: string | undefined = undefined;
// console.log(name.toUpperCase()); // 未判断 undefined
// 正确示例：
// const name: string | undefined = undefined;
// console.log(name?.toUpperCase() || '匿名'); // 可选链判断

"strictFunctionTypes": true, // 严格函数类型检查
// 错误示例（开启后报错）：
// type Fn = (a: number) => void;
// const fn: Fn = (a: any) => {}; // 参数类型不匹配
// 正确示例：
// type Fn = (a: number) => void;
// const fn: Fn = (a: number) => {};

"baseUrl": "./", // 模块解析基础路径为项目根目录
"paths": {
  "@/*": ["src/*"], // @ 指向 src 目录
  "@/components/*": ["src/components/*"] // 组件目录别名
},
// 作用：解决长相对路径问题，如 ../../components/Button → @/components/Button
// 优势：路径更简洁、重构更方便、团队规范统一

// vite.config.ts（必须与 tsconfig.json 别名一致，否则运行时找不到模块）
import { defineConfig } from 'vite';
import path from 'path';
 
export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'), // 与 tsconfig.json 保持一致
    },
  },
});

// 未配置别名时（繁琐且易出错）
import Button from '../../components/Button';
import { formatDate } from '../../utils/date';
 
// 配置别名后（简洁且易维护）
import Button from '@/components/Button';
import { formatDate } from '@/utils/date';

"noUnusedLocals": true, // 禁止未使用的局部变量
"noUnusedParameters": true, // 禁止未使用的函数参数
// 错误示例（开启后报错）：
// const unusedVar = 123; // 未使用的变量
// function fn(unusedParam: number) { return 1; } // 未使用的参数
// 作用：减少死代码，提升代码整洁度，避免变量冗余

"noUncheckedIndexedAccess": true, // 禁止未检查的索引访问
// 错误示例（开启后报错）：
// const arr = [1, 2, 3];
// const item = arr[0]; // 未判断数组长度，item 可能为 undefined
// 正确示例：
// const arr = [1, 2, 3];
// const item = arr[0] ?? 0; // 空值合并判断
// 作用：杜绝数组/对象索引访问导致的运行时错误

"typeRoots": ["./node_modules/@types", "./src/types"],
// 作用：指定类型声明文件的查找目录，默认是 node_modules/@types，扩展自定义类型目录
"types": ["node", "vite/client"],
// 作用：只加载指定的类型声明包，避免加载无用类型，提升编译速度
// 场景：Node 项目需加载 node 类型，Vite 项目需加载 vite/client 类型