【技巧】优雅的使用 pnpm 单体仓库构建一个高效、灵活的多项目架构

单体仓库（Monorepo）搭建指南：从零开始

单体仓库（Monorepo）是一种将多个相关项目集中管理在一个仓库中的开发模式。它可以帮助开发者共享代码、统一配置，并简化依赖管理。本文将通过实际代码示例，详细介绍如何使用 pnpm 搭建一个单体仓库。

1. 创建项目目录

mkdir xxx && cd xxx

• mkdir my-monorepo：mkdir 是“make directory”的缩写，用于创建一个新的目录。
• xxx 是你指定的目录名称，表示要创建一个名为 xxx 的文件夹。例如，你可以将其替换为 my-monorepo，表示创建一个名为 my-monorepo 的目录。
• &&：这是一个逻辑操作符，表示“并且”。它用于将两个命令连接起来，只有当第一个命令执行成功（返回状态码为0）时，才会执行第二个命令。这是一种快捷方式，可以避免手动切换目录。
• cd xxx：cd 是“change directory”的缩写，用于切换到指定的目录。xxx 是你刚刚创建的目录名称，表示切换到该目录中。

代码解析：

• 通过 mkdir && cd 的组合命令，我们可以快速创建并进入项目目录。这一步是搭建任何项目的起点。

    

2. 初始化根目录

pnpm init

    pnpm init 的功能类似于 npm init，用于初始化一个新的 Node.js 项目。它会引导你填写一些基本信息（如项目名称、版本、描述、作者等），并生成一个 package.json 文件。这个文件是项目的配置文件，用于定义项目的依赖、脚本和其他元数据。

代码解析：

• 运行 pnpm init 后，pnpm 会提示你输入项目的基本信息。如果你不想手动输入，可以使用 pnpm init -y，它会自动填充默认值并生成一个 package.json 文件。

3. 配置工作空间 - 在根目录的 package.json 中添加

{
  "private": true,  // monorepo 项目需要设置为私有
  "type": "module",  // 使用 ESM 模块系统
  "workspaces": [
    "packages/*"  // 指定工作空间目录
  ]
}

• “private”: true：将项目设置为私有，避免意外发布到 npm。
• “type”: “module”：启用 ES 模块系统，允许使用 import/export 语法。
• “workspaces”：定义工作空间的路径，packages/* 表示所有位于 packages 文件夹中的子项目。

代码解析：

• 通过配置 workspaces，pnpm 可以识别并管理多个子项目，同时共享依赖和配置。

3.1 创建 packages 目录

mkdir packages

• 创建一个名为 packages 的目录，用于存放所有子项目。

3.2 创建子项目，例如 editor

mkdir packages/editor
cd packages/editor

• pnpm init # 初始化子项目的 package.json

    
子项目的 package.json 示例：

{
  "name": "@my-monorepo/editor",  // 建议使用 @scope 形式命名
  "version": "1.0.0",
  "private": true,
  "main": "index.ts",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "start": "vite"
  },
  "dependencies": {
    // 子项目特定的依赖
  },
  "devDependencies": {
    // 子项目特定的开发依赖
  },
  "peerDependencies": {
    // 如果这是一个库，指定同级依赖
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

代码解析：

• “name”: “@my-monorepo/editor”：使用作用域（@scope）命名子项目，可以避免命名冲突。
• “main”: “index.ts”：指定项目的入口文件。
• “scripts”：定义项目的开发脚本，例如 dev、build 和 start。
• “peerDependencies”：如果子项目是一个库，可以通过 peerDependencies 指定同级依赖，例如 react 和 react-dom。

    

4. 常用的工作空间脚本配置

4.1 在根目录安装依赖

pnpm add -w package-name        # 安装生产依赖
pnpm add -w -D package-name     # 安装开发依赖

• -w：表示在工作空间范围内安装依赖，适用于所有子项目。

4.2 在特定子项目中安装依赖

pnpm add package-name --filter @my-monorepo/editor    # 安装生产依赖
pnpm add -D package-name --filter @my-monorepo/editor # 安装开发依赖

• –filter：指定在特定子项目中安装依赖。

4.3 在多个子项目中安装依赖

pnpm add package-name --filter "./packages/**"        # 为所有子项目安装依赖

• –filter “./packages/**”：为所有位于 packages 文件夹中的子项目安装依赖。

4.4 子项目之间的依赖

pnpm add @my-monorepo/shared --filter @my-monorepo/editor  # editor 依赖 shared 包

• @my-monorepo/shared：子项目之间可以通过 pnpm 直接依赖其他子项目。

注意事项⚠️

子项目版本管理

{
  "version": "workspace:*"  // 使用工作空间协议，自动同步版本
}

• “workspace:*”：使用工作空间协议，自动同步所有子项目的版本。

共享配置文件

# 根目录创建共享配置
touch tsconfig.base.json
touch .eslintrc.js

• tsconfig.base.json：根目录的共享 TypeScript 配置文件。
• .eslintrc.js：根目录的共享 ESLint 配置文件。

子项目继承配置：

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

• “extends”：子项目通过 extends 继承根目录的共享配置。

常用的开发工具配置：

{
  "devDependencies": {
    "typescript": "~5.6.2",
    "vite": "^6.0.5",
    "eslint": "^9.17.0",
    "@types/node": "^22.10.3"
  }
}

• 建议安装在根目录：将开发工具安装在根目录，让所有子项目共享相同的开发工具版本。
  项目结构示例

my-monorepo/
├── package.json
├── pnpm-workspace.yaml (可选)
├── tsconfig.base.json
├── .eslintrc.js
├── packages/
│   ├── editor/
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/
│   └── shared/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/

解析：
    这样的结构可以让您更好地管理多个相关项目，共享代码和配置，同时保持每个项目的独立性。通过 pnpm 的工作空间功能，你可以轻松地在子项目之间共享依赖和配置，提升开发效率。
希望这篇文章能帮助你快速搭建一个高效、灵活的单体仓库项目！