PNPM Workspaces Monorepo 工程化实战详解

爱吃荞麦的壮汉

于 2025-07-15 10:13:40 发布

阅读量561

点赞数 20

CC 4.0 BY-SA版权

文章标签： javascript 前端

本文链接：https://blog.youkuaiyun.com/weixin_67336899/article/details/149347302

PNPM Workspaces Monorepo 工程化实战详解

本文聚焦于如何用 PNPM Workspaces 构建现代前端/全栈 monorepo 工程，涵盖目录结构、依赖管理、构建发布、开发体验、CI/CD、常见问题与最佳实践。

1. 为什么选择 PNPM Workspaces？

极致性能：硬链接+去重，安装速度远超 npm/yarn
强依赖隔离：包间依赖清晰，避免“幽灵依赖”
原生 monorepo 支持：无需额外工具即可 workspace 管理
兼容 Lerna/Turbo/Nx：可与主流构建/发布工具无缝集成

2. 典型目录结构

my-monorepo/
  apps/
    web/           # 前端主应用
    admin/         # 管理后台
  packages/
    ui/            # 组件库
    utils/         # 工具库
  scripts/         # 自动化脚本
  package.json     # 根依赖/脚本
  pnpm-workspace.yaml
  turbo.json       # (可选) Turbo 构建配置

apps/：各端应用（web、admin、mobile…）
packages/：可复用库（UI、工具、hooks…）
scripts/：CI/CD、发布、定制脚本

3. 配置详解

3.1 根 package.json

{
  "name": "my-monorepo",
  "private": true,
  "devDependencies": {
    "pnpm": "^8.0.0",
    "typescript": "^5.0.0",
    "eslint": "^8.0.0",
    "turbo": "^1.10.0"
  },
  "scripts": {
    "dev": "pnpm -r run dev",
    "build": "pnpm -r run build",
    "lint": "pnpm -r run lint",
    "test": "pnpm -r run test"
  }
}

3.2 pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'

3.3 子包 package.json

{
  "name": "@my/ui",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "dependencies": {
    "react": "^18.0.0"
  }
}

跨包依赖直接写："@my/utils": "workspace:*"

4. 依赖管理与开发体验

根目录统一安装依赖：pnpm install
跨包 import 自动软链，无需手动 link
支持 pnpm -r run <script> 一键批量操作所有包
支持 pnpm dev -F web 只启动指定 app
支持 pnpm add <dep> -F @my/ui 只给某包加依赖

5. 构建与发布流程

5.1 构建

各包独立 build 脚本（如 tsc -b、next build）
推荐用 Turbo（turbo.json）做依赖图增量构建

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false
    }
  }
}

执行：pnpm build 或 turbo run build

5.2 发布

可用 changesets 管理多包版本
支持 Lerna/changesets 自动生成 changelog、自动发 npm
发布命令：pnpm publish -r --access public

6. 统一代码规范与 CI/CD

根目录统一 eslint/prettier/jest 配置
husky + lint-staged 做提交前校验
CI/CD 可用 GitHub Actions、GitLab CI，按包/变更范围并行构建

示例 GitHub Actions：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - run: pnpm install
      - run: pnpm build