tsconfig.json与tsconfig.build.json的区别及配置相关疑问

一、tsconfig.json 和 tsconfig.build.json 的区别 #

• tsconfig.json：面向开发环境的配置，会包含项目所有源码（包括测试文件、开发脚本这类无需打包的代码），同时开启开发友好的选项——比如关闭noUnusedLocals避免开发时未用变量报错、开启sourceMap方便调试，include范围通常覆盖所有.ts文件。它主要给IDE和日常开发流程用，保证TypeScript能识别所有代码，提供语法检查和智能提示。
• tsconfig.build.json：专门用于生产构建的配置。它会严格限定打包范围，比如include只指向src目录下的业务代码，排除测试、示例文件；开启更严格的编译规则，比如noUnusedLocals: true、declaration: true（生成类型声明文件），关闭或调整sourceMap适配生产环境；还会指定outDir定义编译后文件的输出路径。它是给tsc编译命令用的，确保只打包需要发布的代码，符合生产要求。

二、能不能合并成单个tsconfig.json文件？ #

可以，但不推荐。
如果要合并，你可以通过注释切换配置或者结合extends+条件逻辑实现，但实际操作会很繁琐。比如：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  // 开发时取消以下注释，构建时重新注释
  // "include": ["src/**/*", "__tests__/**/*"],
  // "compilerOptions": {
  //   "sourceMap": false,
  //   "noUnusedLocals": false
  // }
}

这种方式需要手动切换配置，极易出错。而分开维护两个文件，能让开发、构建的配置逻辑更清晰，维护成本更低——比如在package.json里可以直接指定不同脚本用不同配置：

{
  "scripts": {
    "dev": "tsc --watch",
    "build": "tsc --project tsconfig.build.json"
  }
}

三、.app/.build/.base 是不是TypeScript的内置标识？能不能随便命名？ #

这些后缀不是TypeScript的内置标识，完全可以自定义命名，比如tsconfig.foo.json、tsconfig.dev.json都完全可行。

不同后缀只是社区约定俗成的场景区分方式：

• tsconfig.base.json：作为基础配置文件，存放所有子项目共用的编译选项（比如target、module、lib），其他配置文件通过extends字段继承它，避免重复配置。
• tsconfig.app.json：通常用于应用类项目的配置，和库项目的配置做区分（比如应用无需生成declaration文件，而库需要）。
• tsconfig.build.json：如前文所述，用于生产构建场景。

TypeScript对配置文件名没有强制要求，只要执行tsc时通过--project（简写-p）指定文件路径即可，比如tsc -p ./configs/my-custom-config.json也能正常运行。只是tsconfig.xxx.json的命名方式更直观，方便团队成员快速识别配置用途。

内容的提问来源于stack exchange，提问作者Michael Moreno