FE-08-包管理与 monorepo：pnpm、yarn、workspaces

字数统计: 1.7k字   |   阅读时长≈ 8分

FE-08-包管理与 monorepo：pnpm、yarn、workspaces

本节目标：掌握现代包管理器（pnpm）的优势，理解 monorepo 模式，能用 pnpm workspaces 搭建多包项目。

1. 包管理器演进

1
2
3
4
5
6
7
2009  npm（Node 官方）
2013  Bower（前端专用，已淘汰）
2016  yarn（Facebook，改进 npm）
2017  yarn workspaces（monorepo）
2018  pnpm（节省磁盘、速度快）
2020  pnpm workspaces（推荐 monorepo 方案）
2022  bun（Zig 写的，全功能）

2. npm 的痛点

phantom dependencies（幽灵依赖）：

1
2
3
4
5
6
my-project/
  node_modules/
    package-a/  (依赖 lodash)
    lodash/     ← 在！可以直接 import
  src/index.js
    import _ from 'lodash'  // ← 能跑，但 package.json 里没声明 lodash

node_modules 嵌套地狱：

1
2
3
my-project/node_modules/
  package-a/node_modules/lodash
  package-b/node_modules/lodash  ← 重复！

磁盘浪费：100 个项目 × 100 个相同依赖 = 1 万份副本。

3. pnpm 优势

3.1 硬链接 + 软链接

1
2
3
4
5
6
7
8
~/.local/share/pnpm/store/  ← 真实存储（每个版本只一份）
                              ↓ 硬链接
my-project/
  node_modules/
    .pnpm/                    ← 虚拟 store（按依赖关系组织）
      lodash@4.17.21/         ← 软链接到 store
    package-a -> .pnpm/package-a@1.0.0/node_modules/package-a
    lodash -> .pnpm/lodash@4.17.21/node_modules/lodash

好处：

  • 快：硬链接是文件系统操作，几乎零成本
  • 省空间：所有项目共享 store
  • 无幽灵依赖：只有 dependencies 里声明的包才能 import

3.2 安装速度对比

1
2
3
4
5
小项目（~100 包）：
  npm: 30s   yarn: 20s   pnpm: 5s   bun: 0.3s

中项目（~1000 包）：
  npm: 2min  yarn: 1min  pnpm: 15s  bun: 1s

3.3 常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 安装
pnpm install                 # 全量安装
pnpm add lodash              # 装到 dependencies
pnpm add -D typescript        # devDependencies
pnpm add -g pnpm              # 全局

# 移除
pnpm remove lodash

# 升级
pnpm update                  # 升级所有
pnpm update lodash --latest  # 升级到最新

# 运行脚本
pnpm dev
pnpm build
pnpm test

# 其他
pnpm outdated                # 看哪些可升级
pnpm why lodash              # 依赖树
pnpm list                    # 已装的包

4. workspace（monorepo）

monorepo = 一个仓库管理多个项目。

4.1 优势

  • 共享代码、类型、配置
  • 统一依赖管理
  • 一次 PR 改多个包，原子提交
  • 跨包重构容易

4.2 pnpm workspace 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
my-monorepo/
├── pnpm-workspace.yaml       ← workspace 定义
├── package.json               ← 根 package.json
├── packages/
│   ├── ui/                    ← UI 组件库
│   │   ├── package.json
│   │   └── src/
│   ├── utils/                 ← 工具函数
│   │   ├── package.json
│   │   └── src/
│   ├── app/                   ← 主应用
│   │   ├── package.json
│   │   └── src/
│   └── docs/                  ← 文档站
│       ├── package.json
│       └── src/
└── tooling/                   ← 共享配置
    ├── tsconfig/
    ├── eslint-config/
    └── vite-config/
1
2
3
4
# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'tooling/*'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 根 package.json
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "dev": "pnpm -r --parallel run dev",
    "build": "pnpm -r run build",
    "test": "pnpm -r run test",
    "lint": "pnpm -r run lint"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "prettier": "^3.0.0"
  }
}

4.3 共享依赖

1
2
3
4
5
6
7
8
9
10
11
// packages/ui/package.json
{
  "name": "@my-org/ui",
  "version": "0.1.0",
  "dependencies": {
    "react": "^18.0.0"  // ← 每个子包可以单独声明
  },
  "devDependencies": {
    "@my-org/eslint-config": "workspace:*"  // ← 引用 workspace 包
  }
}

workspace 协议：

  • "workspace:*"：用 workspace 里的最新版本
  • "workspace:^1.0.0"：匹配版本
  • "workspace:1.0.0"：固定版本

4.4 共享配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// tooling/tsconfig/base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true
  }
}

// packages/ui/tsconfig.json
{
  "extends": "@my-org/tsconfig/base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

4.5 Changesets（版本管理）

1
2
pnpm add -Dw @changesets/cli
pnpm changeset init
1
2
3
4
# 改了代码后
pnpm changeset
# 选 affected packages + semver bump
# 自动生成 .md 文件记录变更
1
2
3
# 发版时
pnpm changeset version  # 更新 package.json 版本 + 生成 CHANGELOG
pnpm publish -r         # 发布到 npm

5. Turborepo（增量构建）

痛点：monorepo 里改了一个包，要重新构建所有依赖它的包。

Turborepo 缓存构建结果，只重做必要的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}
1
2
3
turbo run build      # 智能构建（用缓存）
turbo run test       # 测试
turbo run dev        # 并行开发

6. 实战：搭建 monorepo

6.1 初始化

1
2
3
mkdir my-monorepo && cd my-monorepo
pnpm init
mkdir -p packages apps tooling

6.2 workspace 配置

1
2
3
4
5
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - 'tooling/*'

6.3 创建子包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# UI 组件库
mkdir -p packages/ui/src
cat > packages/ui/package.json <<EOF
{
  "name": "@my-org/ui",
  "version": "0.0.1",
  "main": "./src/index.ts",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "lint": "eslint src"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}
EOF
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 主应用
mkdir -p apps/web/src
cat > apps/web/package.json <<EOF
{
  "name": "@my-org/web",
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "dependencies": {
    "@my-org/ui": "workspace:*"
  }
}
EOF

6.4 引用 workspace 包

1
2
3
4
5
6
// apps/web/src/main.tsx
import { Button } from '@my-org/ui';

function App() {
  return <Button>Click me</Button>;
}

7. pnpm vs npm vs yarn 选型

特性 npm yarn pnpm bun
速度 慢 中 快 最快
磁盘占用 大 中 小（store） 小
严格依赖 ❌ ❌ ✅ ✅
monorepo workspaces workspaces workspaces workspaces
稳定性 ✅ ✅ ✅ ⚠️ 新
Node 兼容 ✅ ✅ ✅ 部分

2026 推荐：

  • 新项目：pnpm（默认）
  • 脚本/工具：bun（如可接受新生态）
  • 现有项目：保持现状

8. 依赖管理最佳实践

1. 固定版本还是浮动版本：

1
2
3
4
5
// 严格（推荐生产）
"react": "18.2.0"

// 浮动（库用）
"react": "^18.2.0"

2. 区分 dependencies / devDependencies / peerDependencies：

  • dependencies：运行时必需
  • devDependencies：开发/构建时
  • peerDependencies：库专用，让使用方装

3. lock 文件：永远提交 pnpm-lock.yaml！

4. 漏洞扫描：

1
2
pnpm audit
pnpm audit --fix

5. License 检查：

1
npx license-checker --summary

9. CI/CD 缓存

1
2
3
4
5
6
7
8
9
10
11
12
13
# GitHub Actions
- uses: pnpm/action-setup@v4
  with:
    version: 9

- name: Get pnpm store path
  id: pnpm-cache
  run: echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT

- uses: actions/cache@v4
  with:
    path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}

10. 常见问题

Q: pnpm install 失败 ERR_PNPM_PEER_DEP_ISSUES
A: 加 --no-strict-peer-dependencies 或修复 peer dep 声明。

Q: workspace 包找不到
A: 检查 pnpm-workspace.yaml 路径 pattern；运行 pnpm install 重新链接。

Q: 幽灵依赖（用了未声明的包）
A: pnpm 默认严格，如果一定要用，添加到 package.json 或用 .npmrc 的 shamefully-hoist=true（不推荐）。

Q: lock 文件冲突
A: pnpm install --no-frozen-lockfile 更新，或手动 merge。

小结

工具 选型建议
pnpm 新项目首选，速度快、严格、磁盘省
npm 保守选择，最稳定
yarn 现有 yarn 项目保持
bun 工具/脚本，性能极致
pnpm workspaces monorepo 首选
Turborepo 增量构建、缓存
Changesets 版本管理 + Changelog

核心原则：

  1. 永远提交 pnpm-lock.yaml
  2. workspace 包用 workspace:* 协议
  3. CI 缓存 store 目录
  4. peerDependencies 正确声明
  5. 定期 pnpm audit 修漏洞

下一节讲 React 高级：Hooks 原理、并发渲染、Server Components。

赏

谢谢你请我吃糖果

支付宝
微信

扫一扫，分享到微信

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia-plus根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

主要涉及技术：
Java后端开发、Linux开发、
公众号开发、开源爱好者、Linux

联系QQ:562054870