【架构相关】tsconfig.json 与 tsconfig.node.json、tsconfig.app.json 的关系和作用

现代 TypeScript 项目常见的多项目配置模式，特别适用于包含前端和 Node.js 工具链的全栈项目，会同时包含 tsconfig.json 与 tsconfig.node.json、tsconfig.app.json，你知道这是为什么吗？今天就简单介绍一下。

1. 关系说明

• tsconfig.json 是 TypeScript 项目的根配置文件，常作为基础配置或入口配置，通过 references 字段关联其他子配置（如 tsconfig.node.json 和 tsconfig.app.json），实现多配置的统一管理。
• tsconfig.app.json：用于应用程序代码的 TypeScript 配置，比如Vue 组件、浏览器环境
• tsconfig.node.json：用于 Node.js 环境相关代码的 TypeScript 配置，如项目的构建脚本、服务端逻辑等

2. 各配置文件的作用

tsconfig.json（根配置）：

作为项目的「总配置」，定义公共编译选项或通过 references 关联其他子配置，方便统一执行构建命令（如 tsc -b）。

• 不包含具体编译文件（"files": \[\]）
• 通过 references 字段建立项目引用关系
• 支持项目分层构建和增量编译

tsconfig.app.json：

• 配置应用前端代码的编译选项
• 通常包括 Vue 组件、浏览器 API 相关代码等

tsconfig.node.json：

• 配置 Node.js 环境下的代码编译选项
• 通常包括构建脚本、工具函数等服务端代码

3. 为什么这么做？

• 模块化管理：将不同环境的代码分开配置，便于维护
• 增量编译：只重新编译发生变化的部分，提高构建效率
• 类型检查隔离：不同环境使用不同的编译选项和库定义
• 项目引用：支持跨项目引用和类型检查

**这种拆分的核心目的是：针对不同运行环境（Node.js vs 浏览器）的差异，配置不同的 TypeScript 编译规则，避免类型检查冲突。**这种结构让 TypeScript 能更精准地进行类型检查，同时保持配置的灵活性和可维护性。

下面附上一部分 tsconfig 的配置代码：

tsconfig.json

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

tsconfig.node.json

{
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
    "target": "ES2023",
    "lib": ["ES2023"],
    "module": "ESNext",
    "types": ["node"],
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler", // 使用 bundler 模块解析策略
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true,

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["vite.config.ts"]
}

tsconfig.app.json

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "types": ["vite/client"],

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}