tsconfig.json 解析 - Githubissues

rankangkang commented 8 months ago

使用 ts 开发就免不了要接触 tsconfig 配置，如果你在 github 上面 clone 一个 ts 项目到本地或是自己创建一个，安装之后点击打开 tsconfig.json 大概率会看到首行飘红。（别问，问就是 experience）。

1、tsconfig.json 作用

标识 TS 项目的根目录
配置 TS 编译器
指定编译文件

2、tsconfig.json 重要字段

files - 设置要编译的文件名称。只能指定文件，不能指定文件夹
include - 设置需要进行编译的文件或目录，支持路径匹配模式。如果指定了files选项值，则includes的默认值为[]，否则默认包含当前项目中所有文件["**/*"]
exclude - 设置无需进行编译的文件，支持路径模式匹配

以上，详情见：TSConfig 之 include、exclude 和 files 选项 - 掘金 (juejin.cn)
extends - 引入其他配置文件，继承其配置
```
{
// ...
"extends": "./tsconfig.base.json"
}
```

compilerOptions - 设置与编译流程相关的选项

compilerOptions 选项详细说明如下：

{
"compilerOptions": {
  /* 基本选项 */
  "target": "es5", // 指定 ECMAScript 目标版本: 'ES3' (default), 'ES5', 'ES6'/'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'
  "module": "commonjs", // 指定使用模块: 'commonjs', 'amd', 'system', 'umd' or 'es2015'
  "lib": [], // 指定要包含在编译中的库文件
  "allowJs": true, // 允许编译 javascript 文件
  "checkJs": true, // 报告 javascript 文件中的错误
  "jsx": "preserve", // 指定 jsx 代码的生成: 'preserve', 'react-native', or 'react'
  "declaration": true, // 生成相应的 '.d.ts' 文件
  "sourceMap": true, // 生成相应的 '.map' 文件
  "outFile": "./", // 将输出文件合并为一个文件
  "outDir": "./", // 指定输出目录
  "rootDir": "./", // 用来控制输出目录结构 --outDir.
  "removeComments": true, // 删除编译后的所有的注释
  "noEmit": true, // 不生成输出文件
  "importHelpers": true, // 从 tslib 导入辅助工具函数
  "isolatedModules": true, // 将每个文件做为单独的模块 （与 'ts.transpileModule' 类似）.

  /* 严格的类型检查选项 */
  "strict": true, // 启用所有严格类型检查选项
  "noImplicitAny": true, // 在表达式和声明上有隐含的 any类型时报错
  "strictNullChecks": true, // 启用严格的 null 检查
  "noImplicitThis": true, // 当 this 表达式值为 any 类型的时候，生成一个错误
  "alwaysStrict": true, // 以严格模式检查每个模块，并在每个文件里加入 'use strict'

  /* 额外的检查 */
  "noUnusedLocals": true, // 有未使用的变量时，抛出错误
  "noUnusedParameters": true, // 有未使用的参数时，抛出错误
  "noImplicitReturns": true, // 并不是所有函数里的代码都有返回值时，抛出错误
  "noFallthroughCasesInSwitch": true, // 报告 switch 语句的 fallthrough 错误。（即，不允许 switch 的 case 语句贯穿）

  /* 模块解析选项 */
  "moduleResolution": "node", // 选择模块解析策略： 'node' (Node.js) or 'classic' (TypeScript pre-1.6)
  "baseUrl": "./", // 用于解析非相对模块名称的基目录
  "paths": {}, // 模块名到基于 baseUrl 的路径映射的列表，可基于该特性实现类似路径alias的功能
  "rootDirs": [], // 根文件夹列表，其组合内容表示项目运行时的结构内容
  "typeRoots": [], // 包含类型声明的文件列表
  "types": [], // 需要包含的类型声明文件名列表
  "allowSyntheticDefaultImports": true, // 允许从没有设置默认导出的模块中默认导入。

  /* Source Map Options */
  "sourceRoot": "./", // 指定调试器应该找到 TypeScript 文件而不是源文件的位置
  "mapRoot": "./", // 指定调试器应该找到映射文件而不是生成文件的位置
  "inlineSourceMap": true, // 生成单个 soucemaps 文件，而不是将 sourcemaps 生成不同的文件
  "inlineSources": true, // 将代码与 sourcemaps 生成到一个文件中，要求同时设置了 --inlineSourceMap 或 --sourceMap 属性

  /* 其他选项 */
  "experimentalDecorators": true, // 启用装饰器
  "emitDecoratorMetadata": true // 为装饰器提供元数据的支持
}
}

3、注意事项

tsc --init 命令生成 tsconfig.json 文件。在项目目录下直接 tsc，编译的时候就会走配置文件
有时你会遇到定义了global.d.ts但其中的类型就是无法使用的情况（如无法引入 。module.scss ），很大概率就是你的include字段未包含`.d.ts，导致ts未能编译到.d.ts`文件，引发类型无法使用的情况
```
{
// ...
"include": [
  "src",
  "*.d.ts" // 使得TS能够匹配.d.ts文件
],
"exclude": ["node_modules"]
}
```

使用compilerOptions中的paths字段可实现类似 webpack 路径 alias 功能

{
// ...
"compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@*": ["src/*"]
  }
}
}

类似于 webpack 配置的alias选项：

reslove: {
  alias: {
      '@*': path.resolve(__dirname, 'src/*')
  },
  extensions: ['.js', '.jsx', '.ts', '.tsx']
}
// 但是配置webpack alias 在开发ts项目时还是会遇到问题，如 typescript-eslint 报错，我们还是需要给 tsconfig.json 配置 paths 映射路径

rankangkang commented 8 months ago

4、关于交叉依赖

当你的 ts 项目 A 依赖另一个 ts 项目 B 时，如果你需要对项目 A 进项调试或打包，name你必须先编译 B。在没有“魔法”情况下，我们只能手动的做这件事。

对此，ts 提供了 referrence（依赖项目设置）与 composite（被依赖项目设置）配置来解决依赖编译的问题。

// project A tsconfig.json
{
   // ...
   "references": [
      { "path": "path/to/project/B/tsconfig.json" },
    ],
}

// project B tsconfig.json
{
   "compilerOptions": {
     // ...
     "composite": true, // 使用references 字段引入的配置文件需要设置 composite: true
   },
}

然后在编译时 A 时增加 --build 选项，在 A 编译的同时，B 也会被编译

https://juejin.cn/post/7165429078470688781

rankangkang commented 8 months ago

finally，常用的 tsconfig 配置

参见 https://github.com/tsconfig/bases

rankangkang commented 8 months ago

btw，ts 常用但未内置的联合类型

参见 utility-types: https://github.com/piotrwitek/utility-types

rankangkang / issues

tsconfig.json 解析 #3

1、tsconfig.json 作用

2、tsconfig.json 重要字段

3、注意事项

4、关于交叉依赖

finally，常用的 tsconfig 配置

btw，ts 常用但未内置的联合类型