如何在 Monorepo 中优雅地共享 TypeScript 类型定义

随着前端工程规模的不断扩大，Monorepo 已经成为管理多包项目的标准方案。无论是使用 Turborepo、Nx 还是 pnpm workspace，我们都会面临一个共同的挑战：如何在多个包之间高效、可靠地共享 TypeScript 类型定义？

类型定义是 TypeScript 项目的灵魂。如果类型共享做得不好，轻则导致重复代码，重则引发类型不一致、构建失败甚至运行时错误。本文将深入探讨在 Monorepo 中共享 TypeScript 类型的几种主流方案，并给出经过实践检验的最佳实践。

为什么类型共享在 Monorepo 中如此棘手？

在单包项目中，类型定义天然就在同一个 tsconfig.json 的管辖范围内。但在 Monorepo 中，每个包都有自己的 tsconfig.json，包与包之间存在物理隔离。这带来了几个核心问题：

1. 路径解析：TypeScript 编译器如何找到其他包的类型文件？
2. 构建顺序：类型包是否需要先于使用方构建？
3. 发布策略：类型包是私有还是需要发布到 npm？
4. 开发体验：在 IDE 中能否获得即时的类型提示和跳转？

理解这些问题的本质，才能选择最合适的方案。

方案一：独立的类型包（Shared Types Package）

这是最直观也最常用的方案。创建一个专门存放共享类型的包，例如 @repo/types 或 @myorg/shared-types。

目录结构

packages/
  types/
    src/
      index.ts
      user.ts
      api.ts
    package.json
    tsconfig.json
  web/
  mobile/

关键配置

在 packages/types/package.json 中，关键是正确设置入口字段：

{
  "name": "@repo/types",
  "version": "0.0.0",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  }
}

注意这里直接将 main 和 types 指向源码 .ts 文件，而不是编译后的 .d.ts。这在 Monorepo 内部使用时非常方便，消费方无需等待类型包构建即可获得类型提示。

消费方配置

在 web 包的 tsconfig.json 中，需要配置路径映射：

{
  "compilerOptions": {
    "paths": {
      "@repo/types": ["../types/src/index.ts"],
      "@repo/types/*": ["../types/src/*"]
    }
  }
}

同时在 package.json 中添加依赖：

{
  "dependencies": {
    "@repo/types": "workspace:*"
  }
}

优缺点分析

优点：结构清晰，职责单一，类型可以被所有包复用，版本管理集中。

缺点：如果直接指向源码，消费方的构建工具（如 Vite、Webpack）需要能够处理来自 node_modules 外部的 TypeScript 文件。对于纯类型导入（import type）这通常没问题，但如果类型包中包含运行时代码，就需要额外配置。

方案二：TypeScript Project References

TypeScript 官方提供的 Project References 功能，专为多包项目设计。它允许 TypeScript 理解包与包之间的依赖关系，并支持增量构建。

配置方式

在类型包的 tsconfig.json 中启用复合模式：

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"]
}

在消费方的 tsconfig.json 中引用：

{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "../types" }
  ]
}

优缺点分析

优点：官方方案，支持增量编译，构建性能优秀，类型跳转准确。declarationMap 还能让 IDE 直接跳转到源码。

缺点：配置相对复杂，要求类型包必须先构建才能被消费。在开发过程中需要保持 tsc --watch 运行，否则类型更新不及时。

方案三：路径别名 + 单一 tsconfig base

如果项目规模不大，或者团队希望简化配置，可以采用路径别名的方式，配合一个共享的 tsconfig.base.json。

根目录配置

创建 tsconfig.base.json：

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "paths": {
      "@repo/types": ["./packages/types/src/index.ts"],
      "@repo/types/*": ["./packages/types/src/*"],
      "@repo/utils": ["./packages/utils/src/index.ts"]
    }
  }
}

每个子包的 tsconfig.json 继承这个基础配置：

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "."
  },
  "include": ["src"]
}

优缺点分析

优点：配置简单，开发体验好，无需构建即可获得类型提示。

缺点：路径别名需要构建工具同步配置（Vite 的 resolve.alias、Webpack 的 resolve.alias 等）。如果包需要独立发布，路径别名会导致发布后的类型引用失效。

最佳实践建议

综合以上方案，我推荐以下实践组合：

1. 纯类型用独立包，业务代码用路径别名

将纯粹的类型定义（接口、枚举、DTO）放在 @repo/types 包中，使用方案一的源码直引方式。这类包通常不包含运行时代码，构建工具处理起来没有负担。

2. 使用 import type 显式导入

始终使用 import type { User } from '@repo/types' 而不是 import { User }。这确保类型导入在编译后被完全擦除，不会产生任何运行时代码或循环依赖。

3. 配置 verbatimModuleSyntax

在 tsconfig.base.json 中启用：

{
  "compilerOptions": {
    "verbatimModuleSyntax": true,
    "isolatedModules": true
  }
}

这强制你显式区分类型导入和值导入，避免构建工具在转译时产生歧义。

4. 为类型包设置 sideEffects: false

在类型包的 package.json 中声明：

{
  "sideEffects": false
}

这告诉打包工具该包没有副作用，可以安全地进行 Tree-shaking。

5. 统一使用 workspace 协议

在 pnpm 或 Yarn 中，使用 workspace:* 引用内部包。这确保了本地开发时链接到源码，发布时自动替换为具体版本号。

6. 建立类型检查 CI 流程

在 CI 中添加类型检查步骤：

pnpm -r exec tsc --noEmit

确保所有包的类型定义保持一致，尽早发现类型断裂。

常见陷阱与规避

陷阱一：循环依赖。类型包 A 引用了业务包 B 的类型，而 B 又依赖 A。解决方案是保持类型包的纯净性，类型包不应依赖任何业务包。

陷阱二：类型与实现不同步。接口定义在类型包中，但实现类在业务包中，修改时容易遗漏。建议使用代码生成工具（如 OpenAPI Generator、GraphQL Code Generator）从单一数据源生成类型。

陷阱三：构建顺序问题。如果使用 Project References，务必在 CI 中使用 tsc --build 而不是 tsc，前者会自动处理依赖顺序。

结语

在 Monorepo 中共享 TypeScript 类型定义，没有放之四海而皆准的银弹。小型项目用路径别名即可快速上手，中大型项目建议采用独立类型包配合 Project References。关键在于：保持类型包的纯净、显式使用类型导入、建立自动化的类型检查流程。

优雅的本质不在于配置的复杂程度，而在于团队能否长期维护、新人能否快速理解。选择适合团队当前阶段的方案，并随着项目演进逐步优化，才是真正的优雅之道。

未经允许不得转载：任鹏个人博客 » 如何在 Monorepo 中优雅地共享 TypeScript 类型定义