企业官网建设流程全解析

• 构建工具
• 开发工具
• CLI

@turbo/tsconfig是 Turbo（Rust 编写的 JavaScript/TypeScript 构建系统）monorepo 中面向packages/下全部内部包的一套共享 TypeScript 编译器配置集合。本文以该包的 README.md 为骨架，逐项拆解 base.json 与 library.json 中每个配置项的含义与取舍，并结合create-turbo、turbo-utils、turbo-gen、turbo-types等真实包的继承方式，说明如何在一套 monorepo 中通过extends统一、收敛各 TypeScript 包的编译行为。读完本文，你将掌握共享 tsconfig 的包内组织方式、关键编译选项的实际影响，以及在自己仓库中复刻这套实践的具体做法。

包结构：一个 private 的配置包

@turbo/tsconfig位于 packages/tsconfig 目录，全包只包含三个文件，职责非常单一：

packages/tsconfig/ ├── README.md # 包说明：内部共享的 tsconfig 集合 ├── base.json # 通用基础配置 ├── library.json # 面向库（library）构建的配置，继承 base.json └── package.json # 包元信息

其中 package.json 定义了包名为@turbo/tsconfig，版本为0.0.0，并标记"private": true——这明确说明它不对外发布，仅供仓库内部使用：

{ "name": "@turbo/tsconfig", "version": "0.0.0", "private": true }

README 的原文定义即点明了它的用途："Collection of internal tsconfigs shared between turborepo/packages/"——即 packages 目录下所有内部包共享的 tsconfig 集合。也就是说，这个包本身不产出任何运行时代码，它的"源码"就是那些.json配置模板，消费方是仓库内几十个 TypeScript 包。

base.json：全仓库的基础编译基线

base.json 是所有共享配置的根基，定义了每个内部包都应遵守的编译器基线。它开头声明了$schema指向https://json.schemastore.org/tsconfig，保证在编辑器中能获得完整的键值校验与自动补全。

{ "$schema": "https://json.schemastore.org/tsconfig", "compilerOptions": { "composite": false, "declaration": true, "declarationMap": true, "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "inlineSources": false, "isolatedModules": true, "module": "nodenext", "moduleResolution": "nodenext", "noUnusedLocals": false, "noUnusedParameters": false, "preserveWatchOutput": true, "skipLibCheck": true, "strict": true }, "exclude": ["node_modules", "dist"] }

下面逐项说明每个选项的实际影响：

此外，exclude字段将node_modules与dist排除在编译范围之外，这是 monorepo 中防止误编译依赖产物或已生成文件的标配做法。

library.json：面向库构建的配置组合

library.json 通过"extends": "./base.json"继承基础配置，再按"库（library）"这一构建形态补充差异化选项：

{ "extends": "./base.json", "compilerOptions": { "lib": ["ES2019"], "target": "ES2019", "skipLibCheck": true, "resolveJsonModule": true, "outDir": "dist", "allowJs": false } }

各配置项解读如下：

• target: "ES2019"与lib: ["ES2019"]：把编译目标与可用标准库锁定在 ES2019。这是一个保守的兼容基线——产物面向较旧的 Node 运行时也能运行，同时lib明确限定类型声明来源，避免误用超出目标的 API。
• skipLibCheck: true：在 base 基础上再次显式声明，强调库包类型检查时跳过.d.ts校验。
• resolveJsonModule: true：允许直接import data from "./data.json"导入 JSON 文件并得到类型推断。@turbo/tsconfig的消费者（如turbo-gen）会加载模板 JSON 等资源，此选项必不可少。
• outDir: "dist"：统一所有内部包的编译输出目录为dist，与 Turbo 任务缓存、产物清理约定保持一致。
• allowJs: false：禁止直接编译.js文件，保证包内输出全部由 TypeScript 源码生成，维持声明与实现的一致性。

注意extends: "./base.json"使用的是相对于 library.json 自身的路径——这也是共享 tsconfig 包内的推荐写法；而各消费包则通过包名@turbo/tsconfig/library.json来引用（见下节）。

仓库内的真实继承方式：包名引用 + 局部覆盖

整个packages/目录下，已有大量内部包通过"extends": "@turbo/tsconfig/library.json"接入这套配置，并在此基础上做局部覆盖，形成"共享基线 + 按包微调"的分层模式。以下是四个有代表性的真实示例：

1. create-turbo/tsconfig.json：脚手架工具，需要模板文件与 DOM API

{ "extends": "@turbo/tsconfig/library.json", "exclude": ["templates"], "compilerOptions": { "rootDir": ".", "lib": ["ES2022", "DOM"], "strictNullChecks": true } }

它额外排除了templates目录（模板不作为源码编译），把lib提升到ES2022并加入DOM，同时显式打开strictNullChecks——说明共享基线允许各包按自身需求把lib提升到更新版本，而不用等全仓库统一升级。

2. turbo-utils/tsconfig.json：工具函数库，配置与 create-turbo 几乎一致（rootDir: "."、lib: ["ES2022", "DOM"]、strictNullChecks: true），说明rootDir与strictNullChecks是这批内部包的高频覆盖项。

3. turbo-gen/tsconfig.json：代码生成器，模块策略单独定制

{ "extends": "@turbo/tsconfig/library.json", "exclude": ["src/templates", "scripts", "dist", "node_modules"], "compilerOptions": { "rootDir": ".", "lib": ["ES2022", "DOM"], "module": "preserve", "moduleResolution": "bundler", "strictNullChecks": true } }

turbo-gen把module覆盖为preserve、moduleResolution覆盖为bundler，贴近现代打包器（如 Vite/esbuild）的解析语义，同时排除src/templates、scripts等非产物目录。这展示了共享配置的另一个价值：需要偏离基线的包可以显式覆盖，且这种偏离被限定在单个包内。

4. turbo-types/tsconfig.json：类型包，最贴近共享基线

{ "extends": "@turbo/tsconfig/library.json", "compilerOptions": { "rootDir": ".", "module": "nodenext", "lib": ["ESNext"], "strictNullChecks": true }, "exclude": ["node_modules", "scripts"] }

作为纯类型库，它仅微调了lib到ESNext、module回到nodenext，其余完全继承共享配置，是"开箱即用"消费方式的最好例证。

与仓库根 tsconfig.json 的分工

值得注意的是，仓库根目录的 tsconfig.json并不继承@turbo/tsconfig，它是一份独立的轻量配置，主要服务于仓库根层级的工具链与路径别名（@vercel/webpack-nft的paths映射）。这揭示了 Turbo 仓库的配置分层思想：

• 根 tsconfig.json：面向根目录工具与构建辅助，定义全局路径别名；
• @turbo/tsconfig/base.json：全仓库包的编译基线（strict、nodenext、声明生成等）；
• @turbo/tsconfig/library.json：库包的推荐形态（ES2019 目标、dist 输出、JSON 导入）；
• 各包自身 tsconfig.json：通过包名 extends + 局部覆盖，表达自身的lib、rootDir、模块策略等差异。

这套"根级 + 共享包级 + 包级"三层结构，正是 Turbo 官方在自举（dogfooding）monorepo 时沉淀下来的最佳实践范本。

实战要点总结

1. 共享配置应以独立的 private npm 包存在：将base.json/library.json放进packages/tsconfig这样的包目录，消费者用extends: "@turbo/tsconfig/library.json"按包名引用，比extends: "../../../tsconfig.base.json"这类相对路径更稳定，也不受目录移动影响。
2. 善用继承与覆盖的平衡：把全仓库共识（strict、esModuleInterop、skipLibCheck、exclude: ["node_modules", "dist"]）沉淀进 base，把某类构建形态（库、CLI、工具）的默认值沉淀进中间层（如library.json），把包级差异（lib、module、exclude）留在各包自己的 tsconfig 里，避免"一把大伞"式的单一配置。
3. 编译产物约定统一：outDir: "dist"、declaration与declarationMap的组合让所有内部包的产物形态一致，既利于 Turbo 的缓存与依赖图，也方便上游包消费.d.ts。
4. isolatedModules为转译器铺路：开启它意味着每个文件可被 Babel/SWC/esbuild 独立转译，这与 Turbo 生态中常见的快速转译路径天然兼容。

如果需要查看这些配置的实际消费效果，可对照 packages/create-turbo/tsconfig.json、packages/turbo-gen/tsconfig.json 与 packages/turbo-types/tsconfig.json，以及各包在 packages 目录下的完整源码实现。

• 构建工具
• 开发工具
• CLI