tsconfig

一个目录下如果存在tsconfig.json文件（下称TS配置），那么该目录意味着是一个TS项目的根目录。

TS配置的作用是告诉编译器（比如tsc、rollup等）应该如何编译TS文件，编译器在工作时，会读取TS配置，如果不存在这个文件的话，将会使用缺省的配置文件去编译TS文件。

编译配置的选项很多，这里介绍比较常用的。

files、exclude、include

指定哪些文件需要被TS处理。

当这些需要被TS处理的文件较少时, 可以考虑使用files字段, 如果需要被处理的文件比较多, 可以考虑使用include和exclude，它们按照files > exclude > include的优先级去匹配文件。

files

• default：false

不指定时包含项目下所有的TS文件，在allowJs = true时还会包含JS文件。

{
  "files": ["core.ts", "types.ts", "utils.ts"]
}

include

• default：[]

跟files配置表现效果一致。

{
  "include": ["src/**/*", "tests/**/*"]
}

exclude

• default：[node_modules, bower_components, jspm_packages, <outDir>]

对指定的文件跳过编译。

{
  "exclude": ["node_modules"]
}

extends

用于指定一个基础配置文件，以继承其配置选项。

{
  "extends": "./tsconfig.base.json",
}

references

声明当前项目依赖的其他TS项目（通常用于monorepo），启用增量构建和跨项目类型检查。比如在monorepo项目拆分为多个子项目（如frontend、backend、shared-lib），管理它们之间的依赖关系。

{
  "references": [
    { "path": "../shared" }, // 依赖 shared 项目
    { "path": "../utils" }   // 依赖 utils 项目
  ]
}

WARNING

需要注意的是，被引入的模块要开启compilerOptions.composite = true，references才会生效，否则在tsc -b的时候会报错。

框架项目的references

但是在创建新的vue项目时，存在下面的代码：

{
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

这是因为vue项目的references仅仅是用于IDE支持，同时理解多个配置上下文，而不是真正的项目引用构建，vue项目不会用tsc --build去构建项目内的TS文件。

compilerOptions

配置编译器的编译选项。

{
  "compilerOptions": {

    /* 基本选项 */
    "target": "es5", // 生成代码的 ECMAScript 目标版本
    "module": "commonjs", // 生成代码的模块标准
    "lib": ["es6", "dom"], // 告诉 TypeScript 编译器要包括哪些环境的类型声明文件（`.d.ts` 文件）
    "allowJs": true, // 是否编译 JS 文件
    "checkJs": true, // 是否在 JS 文件中报告错误
    "jsx": "preserve", // 在 .tsx 文件里支持 JSX: 'preserve', 'react-native', or 'react'
    "declaration": true, // 是否生成 .d.ts 类型定义文件
    "emitDeclarationOnly": true, // 只生成类型声明文件，不生成js
    "declarationMap": true, // 为每个 .d.ts 文件生成 sourcemap
    "sourceMap": true, // 是否生成 .map 文件
    "outFile": "./dist/main.js", // 将多个输出文件合并为一个文件，`module`为`None` 、 `System`或`AMD` 时可用，CommonJS 或 ES6 模块。不可用
    "outDir": "./dist", // 输出文件夹
    "rootDir": "./", // 指定 TypeScript 编译器查找 TypeScript 文件的根目录，通常用于控制输入文件的搜索路径。假设你的 TypeScript 文件存储在项目的根目录下，你可以配置为 './'
    "composite": true, // 生成额外的元数据文件，这些文件可以帮助构建工具（包括TypeScript自身的--build模式）更快地确定项目是否已经被构建。
    "removeComments": true, // 删除注释
    "noEmit": true, // 不输出文件
    "importHelpers": true, // 通过 tslib 引入辅助工具函数
    "downlevelIteration": true, // 是否添加对迭代器和生成器的补丁（es6+无需关注）
    "useDefineForClassFields": true, // 是否使用 Object.defineProperty 定义类实例属性

    /* 严格的类型检查 */
    "strict": true, // 启用所有严格类型检查
    "noImplicitAny": true, // 不允许隐式的 any 类型
    "strictNullChecks": true, // 不允许把 null、undefined 赋值给其他类型变量
    "strictFunctionTypes": true, // 严格检查函数的类型
    "strictBindCallApply": true, // 严格检查 bind、call 和 apply 的参数规则
    "strictPropertyInitialization": true, // 类的实例属性必须初始化
    "noImplicitThis": true, // 不允许 this 有隐式的 any类型
    "noUnusedLocals": true, // 检查未使用的局部变量
    "noUnusedParameters": true, // 检查未使用的参数
    "noImplicitReturns": true, // 每个分支都会有返回值
    "noFallthroughCasesInSwitch": true, // 检查 switch 语句包含正确的 break

    /* 模块解析 */
    "isolatedModules": true, // 控制是否将每个文件作为单独的模块处理。
    "moduleResolution": "node", // 模块解析策略
    "allowImportingTsExtensions": true, // 允许在导入 TypeScript 文件时指定文件扩展名（如 `.ts`, `.tsx`），当导入路径需要显式包含文件扩展名时，确保兼容性
    "baseUrl": "./", // 解析使用非相对路径导入模块时的基地址
    "paths": {}, // 模块名称到基于 baseUrl 的路径映射表
    "rootDirs": [], // 将多个文件夹放在一个虚拟目录下，合并多个源文件目录
    "typeRoots": [], // typeRoots用来指定声明文件或文件夹的路径列表，如果指定了此项，则只有在这里列出的声明文件才会被加载
    "types": [], // types用来指定需要包含的模块，只有在这里列出的模块的声明文件才会被加载进来
    "allowSyntheticDefaultImports": true, // 允许从没有默认导出的模块默认导入
    "esModuleInterop": true, // 通过创建命名空间实现 CommonJS 兼容性
    "resolveJsonModule": true, // 自动解析JSON文件

    /* Source Map */
    "sourceRoot": "", // TypeScript 源代码所在的目录
    "mapRoot": "", // mapRoot用于指定调试器找到映射文件而非生成文件的位置，指定map文件的根路径，该选项会影响.map文件中的sources属性
    "inlineSourceMap": true, // 生成单个 sourcemaps 文件,而不是将 sourcemaps 生成不同的文件
    "inlineSources": true, // 将代码与 sourcemaps 生成到一个文件中

    /* 实验性 */
    "experimentalDecorators": true, // 启用实验性的装饰器特性
    "emitDecoratorMetadata": true // 为装饰器提供元数据支持
  }
}