搭建vue3中后台管理模版 (二) - tsconfig.json 配置项

在 TypeScript 项目开发中，存在一个 tsconfig.json 配置文件

作为 TS 项目中最常见的配置文件，有必要了解下其各项配置

什么是 tsconfig.json

TypeScript 使用 tsconfig.json 文件作为其配置文件，当一个目录中存在 tsconfig.json 文件，则认为该目录为 TypeScript 项目的根目录。

配置文件的作用：

• 指定待编译文件 file、include、exclude
• 定义编译选项 compilerOptions

vite 中 tsconfig 默认选项

tsconfig.json

{
    "compilerOptions": {
        // 将代码编译为最新版本的 JS
        "target": "ESNext",
        // 使用 Object.defineProperty 定义 class 中的属性，而非使用 obj.key = value 的形式定义属性
        "useDefineForClassFields": true,
        // 使用 ES Module 格式打包编译后的文件
        "module": "ESNext",
        // 使用 Node 的模块解析策略
        "moduleResolution": "Node",
        // 启用所用严格的类型检查
        "strict": true,
        // 保留原始的 JSX 代码，不进行编译
        "jsx": "preserve",
        // 生成 sourceMap 文件
        "sourceMap": true,
        // 允许引入 JSON 文件
        "resolveJsonModule": true,
        // 该属性要求所有文件都是 ES Module 模块。
        "isolatedModules": true,
        // 允许使用 import 引入使用 export = 导出的内容
        "esModuleInterop": true,
        // 引入 ES 最新特性和 DOM 接口的类型定义
        "lib": ["ESNext", "DOM"],
        // 跳过对 .d.ts 文件的类型检查
        "skipLibCheck": true
    },
    // 包含文件编译的匹配模式
    "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
    // 引入 `tsconfig.node.json` 中的配置
    "references": [{ "path": "./tsconfig.node.json" }]
}

tsconfig.node.json

{
    "compilerOptions": {
        // 对于引用项目必须设置该属性
        "composite": true,
        // 使用 ES Module 格式打包编译后的文件
        "module": "ESNext",
        // 使用 Node 的模块解析策略
        "moduleResolution": "Node",
        // 允许使用 import 导入使用 export = 导出的默认内容 
        "allowSyntheticDefaultImports": true
    }
    // 包含文件编译的匹配模式，这里配置只针对 vite.config.ts
    "include": ["vite.config.ts"]
}

常用配置项

compilerOptions 编译选项, 可以被忽略，这时编译器会使用默认值。在这里查看完整的 编译器选项 列表。

编译选项配置非常繁杂，有很多配置，这里只列出常用的配置。

选项	类型	默认值	描述
target	string	"ES3"	指定ECMAScript目标版本 "ES3"（默认）， "ES5"， "ES6"/ "ES2015"， "ES2016"， "ES2017"或 "ESNext"。
module	string	target === "ES6" ? "ES6" : "commonjs"	指定生成哪个模块系统代码： "None"， "CommonJS"， "AMD"， "System"， "UMD"， "ES6"或 "ES2015"。 只有 "AMD"和 "System"能和 --outFile一起使用。"ES6"和 "ES2015"可使用在目标输出为 "ES5"或更低的情况下。
moduleResolution	string	module === "AMD" or "System" or "ES6" ? "Classic" : "Node"	决定如何处理模块。或者是"Node"对于Node.js/io.js，或者是"Classic"（默认）。查看模块解析了解详情。
removeComments	boolean	false	删除所有注释，除了以 /!*开头的版权信息。
useDefineForClassFields	boolean	false	使用 Object.defineProperty 定义 class 中的属性，而非使用 obj.key = value 的形式定义属性
strict	boolean	false	启用所有严格类型检查选项。启用 --strict相当于启用 --noImplicitAny, --noImplicitThis, --alwaysStrict， --strictNullChecks和 --strictFunctionTypes和--strictPropertyInitialization。
noImplicitAny	boolean	false	在表达式和声明上有隐含的 any类型时报错。
noImplicitThis	boolean	false	当 this表达式的值为 any类型的时候，生成一个错误
alwaysStrict	boolean	false	以严格模式解析并为每个源文件生成 "use strict"语句
strictNullChecks	boolean	false	在严格的 null检查模式下， null和 undefined值不包含在任何类型里，只允许用它们自己和 any来赋值（有个例外， undefined可以赋值到 void）。
strictFunctionTypes	boolean	false	禁用函数参数双向协变检查。
strictPropertyInitialization	boolean	false	确保类的非undefined属性已经在构造函数里初始化。若要令此选项生效，需要同时启用--strictNullChecks。
jsx	string	"Preserve"	在 .tsx文件里支持JSX： "React"或 "Preserve"。查看 JSX。
jsxFactory	string	"React.createElement"	指定生成目标为react JSX时，使用的JSX工厂函数，比如 React.createElement或 h。
sourceMap	boolean	false	生成相应的 .map文件
resolveJsonModule	boolean	false	允许引入 JSON 文件
isolatedModules	boolean	false	该属性要求所有文件都是 ES Module 模块
esModuleInterop	boolean	false	允许使用 import 引入使用 export = 导出的内容
skipLibCheck	boolean	false	跳过对 .d.ts 文件的类型检查
lib	string[]		引入 ES 最新特性和 DOM 接口的类型定义
composite	boolean	false	对于引用项目必须设置该属性
allowSyntheticDefaultImports	boolean	false	允许使用 import 导入使用 export = 导出的默认内容
declaration	boolean	false	生成相应的 .d.ts文件。
declarationDir	string		生成声明文件的输出路径。
rootDirs	string[]		将多个目录放在一个虚拟目录下，用于运行时，即编译后引入文件的位置可能发生变化，这也设置可以虚拟src和out在同一个目录下，不用再去改变路径也不会报错

files

指定一个包含相对或绝对文件路径的列表

{
    "files": ["core.ts", "sys.ts"]
}

include、exclude

include 包含项、 exclude 排除项

指定一个文件glob匹配模式列表。 支持的glob通配符有：

• * 匹配0或多个字符（不包括目录分隔符）
• ? 匹配一个任意字符（不包括目录分隔符）
• **/ 递归匹配任意子目录

{
    "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
    "exclude": ["node_modules", "**/*.spec.ts"]
}

references

引用的工程必须启用新的compilerOptions.composite设置。这个选项用于帮助TypeScript快速确定引用工程的输出文件位置。

• 对于rootDir设置，如果没有被显式指定，默认为包含tsconfig文件的目录
• 所有的实现文件必须匹配到某个include模式或在files数组里列出。如果违反了这个限制，tsc会提示你哪些文件未指定。
• 必须开启declaration选项。

TypeScript 3.0的新特性, 顶层属性references, 它是一个对象的数组，指明要引用的工程

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

每个引用的path属性都可以指向到包含tsconfig.json文件的目录，或者直接指向到配置文件本身（名字是任意的）。

当你引用一个工程时，会发生下面的事：

• 导入引用工程中的模块实际加载的是它输出的声明文件（.d.ts）。
• 如果引用的工程生成一个outFile，那么这个输出文件的.d.ts文件里的声明对于当前工程是可见的。
• 构建模式（后文）会根据需要自动地构建引用的工程。

当你拆分成多个工程后，会显著地加速类型检查和编译，减少编辑器的内存占用，还会改善程序在逻辑上进行分组。

参考

TypeScript中文网 - tsconfig-json