002 vue3-admin项目的目录及文件说明之tsconfig.json文件

说明

tsconfig.json 是 TypeScript 项目的核心配置文件，用于指定 TypeScript 编译器的编译选项和项目设置。

基本结构

{
  "compilerOptions": {
    /* 编译选项 */
  },
  "include": [
    /* 包含文件 */
  ],
  "exclude": [
    /* 排除文件 */
  ],
  "extends": "/* 继承配置 */",
  "files": [
    /* 指定文件 */
  ],
  "references": [
    /* 项目引用 */
  ]
}

核心配置项

1 compilerOptions 属性

"compilerOptions": {
  "target": "ES2020",
  "lib": ["ES2020", "DOM", "DOM.Iterable"],
  "module": "ESNext",
  "moduleResolution": "bundler",
  "jsx": "preserve"
}

• target：指定编译后的 JavaScript 版本
• lib：指定要包含的库文件
• module：指定生成的模块代码类型
• moduleResolution：指定模块解析策略
• jsx：指定 JSX 代码的处理方式

严格模式配置：

"compilerOptions": {
  "strict": true,
  "noImplicitAny": true,
  "strictNullChecks": true,
  "strictFunctionTypes": true,
  "strictBindCallApply": true,
  "strictPropertyInitialization": true,
  "noImplicitThis": true,
  "useUnknownInCatchVariables": true,
  "alwaysStrict": true
}

• strict：启用所有严格类型检查选项
• noImplicitAny：禁止隐式的 any 类型
• strictNullChecks：启用严格的 null 和 undefined 检查
• 其他严格选项：提供更严格的类型检查

模块解析配置

"compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@/*": ["src/*"]
  },
  "rootDirs": ["src", "tests"],
  "typeRoots": ["node_modules/@types", "src/types"],
  "types": ["node", "jest"]
}

• baseUrl：设置基础路径
• paths：配置路径映射（别名）
• rootDirs：设置根目录列表
• typeRoots：指定类型声明文件的目录
• types：指定要包含的类型声明包

输出配置：

"compilerOptions": {
  "outDir": "./dist",
  "rootDir": "./src",
  "declaration": true,
  "declarationDir": "./dist/types",
  "sourceMap": true,
  "inlineSourceMap": false,
  "outFile": "./dist/bundle.js"
}

• outDir：指定输出目录
• rootDir：指定输入文件的根目录
• declaration：生成类型声明文件
• sourceMap：生成源映射文件
• outFile：将输出合并为单个文件

检查与报告配置

"compilerOptions": {
  "noUnusedLocals": true,
  "noUnusedParameters": true,
  "noImplicitReturns": true,
  "noFallthroughCasesInSwitch": true,
  "forceConsistentCasingInFileNames": true,
  "skipLibCheck": true
}

• noUnusedLocals：禁止未使用的局部变量
• noUnusedParameters：禁止未使用的参数
• noImplicitReturns：要求函数有明确的返回值
• 其他检查选项：提高代码质量

2 include 属性

"include": [
  "src/**/*.ts",
  "src/**/*.tsx",
  "src/**/*.vue",
  "tests/**/*.ts"
]

• 作用：指定要编译的文件模式
• 支持 glob 模式：
  • *：匹配零个或多个字符（不包括目录分隔符）
  • ?：匹配单个字符（不包括目录分隔符）
  • **/：匹配嵌套目录

3 exclude 属性

"exclude": [
  "node_modules",
  "dist",
  "build",
  "**/*.spec.ts",
  "**/*.test.ts"
]

• 作用：指定要排除的文件模式
• 优先级：files > include > exclude
• 默认排除：默认排除 node_modules、bower_components、jspm_packages

4 extends 属性

"extends": "@vue/tsconfig/tsconfig.dom.json"

• 作用：继承其他配置文件
• 支持路径：相对路径或 npm 包名
• 优先级：继承的配置会被当前配置覆盖

5 files 属性

"files": [
  "src/main.ts",
  "src/polyfills.ts"
]

• 作用：明确指定要编译的文件列表
• 优先级：高于 include 和 exclude
• 适合场景：指定核心入口文件

 

6 references 属性

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

• 作用：指定项目引用
• 用途：支持 TypeScript 项目的模块化
• 优势：提高大型项目的编译性能

 

与tsconfig.app.json、tsconfig.node.json文件关系

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

 

1 files 属性

• 作用：指定要编译的文件列表
• 特点：这里是空数组，表示不直接编译任何文件
• 意图：主配置文件仅作为项目引用的入口，具体编译配置由子项目负责

2 references 属性

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

• 作用：指定项目引用列表
• 包含的子项目：
  • ./tsconfig.app.json：应用代码的配置文件
  • ./tsconfig.node.json：Node.js 相关代码的配置文件

项目引用（Project References）机制

什么是项目引用？

• TypeScript 30+ 引入的功能
• 允许将大型 TypeScript 项目拆分为多个子项目
• 支持增量编译，提高编译性能

工作原理

1 主配置文件：作为项目的根配置，引用其他子项目2 子项目配置：每个子项目有自己的 tsconfig.json 文件3 依赖关系：子项目之间可以相互引用4 增量编译：只重新编译发生变化的子项目

项目结构推测

根据这个配置，项目结构可能如下：

project/
├── tsconfig.json          # 主配置文件（项目引用入口）
├── tsconfig.app.json      # 应用代码配置
├── tsconfig.node.json     # Node.js 代码配置
├── src/                   # 应用源代码
│   ├── main.ts
│   ├── app/
│   └── ...
└── node/                  # Node.js 相关代码
    ├── scripts/
    └── ...

 

优势分析

1 性能优化

• 增量编译：大幅提高编译速度
• 并行编译：支持多线程并行编译子项目
• 缓存机制：利用 .tsbuildinfo 文件缓存编译信息

2 代码组织

• 模块化结构：清晰的项目边界
• 职责分离：不同类型的代码有独立配置
• 依赖管理：明确的项目间依赖关系

3 开发体验

• IDE 支持：现代 IDE 对项目引用有良好支持
• 类型检查：跨项目的类型检查正常工作
• 构建工具：与 Vite、Webpack 等构建工具兼容

常见应用场景

1 前端框架项目

• tsconfig.app.json：浏览器端应用代码
• tsconfig.node.json：构建脚本、工具脚本

2 全栈应用

• tsconfig.frontend.json：前端代码
• tsconfig.backend.json：后端代码

3 库开发

• tsconfig.core.json：核心功能
• tsconfig.utils.json：工具函数
• tsconfig.test.json：测试代码

总结

这个 tsconfig.json 文件采用了 TypeScript 的项目引用功能，将项目拆分为应用代码和 Node.js 代码两个子项目。这种配置方式特别适合现代前端工程，能够显著提高编译性能，改善代码组织，是大型 TypeScript 项目的最佳实践之一。