pnpm + Monorepo 使用教程（集成 Vue 3 项目）

📦 pnpm + Monorepo 使用教程（集成 Vue 3 项目）

本文档指导你将现有 Vue 3 项目 my-space-web 迁移到基于 pnpm 的 monorepo 架构中，实现高效、可扩展的多包管理。

📚 目录

[1. 为什么使用 pnpm + Monorepo？](#1. 为什么使用 pnpm + Monorepo？)
[2. 准备工作](#2. 准备工作)
[3. 创建 Monorepo 根项目](#3. 创建 Monorepo 根项目)
[4. 迁移 Vue 3 项目到 packages/](#4. 迁移 Vue 3 项目到 packages/)
[5. 清理 npm 痕迹并配置子包](#5. 清理 npm 痕迹并配置子包)
[6. 安装依赖并验证运行](#6. 安装依赖并验证运行)
[7. （可选）添加共享工具库](#7. （可选）添加共享工具库)
[8. 常用命令速查](#8. 常用命令速查)
[9. 常见问题排查](#9. 常见问题排查)

1. 为什么使用 pnpm + Monorepo？

优势	说明
✅ 节省磁盘空间	所有依赖只存一份（硬链接），避免 `node_modules` 膨胀
✅ 严格依赖隔离	杜绝"幽灵依赖"，提升项目健壮性
✅ 原生 Workspace 支持	轻松管理多个相互依赖的子项目
✅ 统一构建/测试流程	通过 `pnpm -r run xxx` 一键操作所有包
✅ 团队协作标准化	通过 `packageManager` 字段锁定 pnpm 版本

适用于：微前端、组件库、工具函数共享、多应用共存等场景。

2. 准备工作

确保已安装：

Node.js ≥ v18（推荐 LTS）
pnpm ≥ v8（推荐 v10+）

安装 pnpm（若未安装）

bash 复制代码

npm install -g pnpm

启用 Corepack（Node.js 内置，通常默认开启）

bash 复制代码

corepack enable

3. 创建 Monorepo 根项目

创建并进入根目录

bash 复制代码

mkdir my-trust-monorepo && cd my-trust-monorepo

初始化根 package.json

bash 复制代码

pnpm init

编辑根目录配置

package.json（根目录）

json 复制代码

{
  "name": "my-trust-monorepo",
  "private": true,
  "packageManager": "pnpm@10.28.0",
  "workspaces": ["packages/*"]
}

pnpm-workspace.yaml（根目录，推荐）

yaml 复制代码

packages:
  - 'packages/*'

✅ 说明：

"private": true 防止根项目被误发布

workspaces 告诉 pnpm 子包位置

packageManager 锁定 pnpm 版本，确保团队一致性

4. 迁移 Vue 3 项目到 packages/

假设你的 Vue 3 项目路径为：
D:/projects/my-space-web

迁移项目到 monorepo 中

Windows PowerShell

powershell 复制代码

Move-Item D:/projects/my-space-web ./packages/my-space-web

手动操作（复制粘贴到）：

复制代码

my-trust-monorepo/
└── packages/
    └── my-space-web/   # 你的 Vue 3 项目

5. 清理 npm 痕迹并配置子包

5.1 进入 Vue 项目目录

bash 复制代码

cd packages/my-space-web

5.2 删除 npm 相关文件

bash 复制代码

# 删除 lock 文件和 node_modules
rm -f package-lock.json
rm -rf node_modules

5.3 确保 package.json 有正确配置

packages/my-space-web/package.json

json 复制代码

{
  "name": "my-space-web",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.4.0"
    // ... 其他依赖
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "@vitejs/plugin-vue": "^5.0.0",
    "vue-tsc": "^2.0.0"
    // ... 其他 devDeps
  }
}

⚠️ 关键 ：必须有 "name": "my-space-web"，否则 pnpm 无法识别为 workspace 包。

6. 安装依赖并验证运行

6.1 回到根目录，安装所有依赖

bash 复制代码

cd ../..
pnpm install

✅ pnpm 会：

读取 workspaces 配置

扫描 packages/*

安装依赖并生成 pnpm-lock.yaml（在根目录）

6.2 启动 Vue 应用

方式一：使用 filter 命令

bash 复制代码

pnpm run dev --filter my-space-web

方式二：进入目录执行

bash 复制代码

cd packages/my-space-web
pnpm run dev

✅ 成功标志 ：若 Vite 开发服务器正常启动（如 http://localhost:5173），说明迁移成功！

7. （可选）添加共享工具库

未来你可能需要共享工具函数、API 客户端等。

7.1 创建 shared 包

bash 复制代码

mkdir -p packages/shared
cd packages/shared
pnpm init

7.2 设置 package.json

json 复制代码

{
  "name": "shared",
  "version": "1.0.0",
  "main": "index.js",
  "types": "index.d.ts"
}

7.3 创建示例文件

packages/shared/index.js

javascript 复制代码

export const API_URL = 'https://api.trust.com';
export const formatDate = (date) => new Date(date).toLocaleDateString();

7.4 在 Vue 项目中引用 shared

在根目录执行：

bash 复制代码

pnpm add shared@workspace:* --filter my-space-web

在 Vue 代码中使用：

javascript 复制代码

// src/main.ts 或任意组件
import { API_URL } from 'shared';
console.log(API_URL); // → https://api.trust.com

✅ 提示：修改 shared 后需重新构建（若含 TS/打包），但 JS 文件可直接热更新。

8. 常用命令速查

基础命令

场景	命令
安装所有依赖	`pnpm install`（根目录）
启动 Vue 应用	`pnpm run dev --filter my-space-web`
构建 Vue 应用	`pnpm run build --filter my-space-web`
给 Vue 加依赖	`pnpm add axios --filter my-space-web`
给 Vue 加 devDep	`pnpm add -D eslint --filter my-space-web`
构建所有包	`pnpm -r run build`
并行构建所有包	`pnpm -r --parallel run build`
查看 workspace 列表	`pnpm ls --workspaces`

快捷脚本配置

建议在根 package.json 添加快捷脚本：

json 复制代码

{
  "scripts": {
    "dev": "pnpm --filter my-space-web dev",
    "build": "pnpm --filter my-space-web build",
    "build:all": "pnpm -r run build",
    "test:all": "pnpm -r run test"
  }
}

使用示例：

bash 复制代码

pnpm dev      # 启动 Vue 应用
pnpm build    # 构建 Vue 应用
pnpm build:all # 构建所有包

9. 常见问题排查

❌ 问题：`ERR_PNPM_WORKSPACE_PKG_NOT_FOUND`

原因：子包缺少 name 字段，或根目录未配置 workspaces。

解决：

检查 packages/my-space-web/package.json 是否有 "name": "my-space-web"
检查根目录是否有 workspaces: ["packages/*"]

❌ 问题：启动报错 "Cannot find module 'vue'"

原因：旧 node_modules 残留或未正确安装。

解决：

bash 复制代码

# 删除所有 node_modules 和 lock 文件
find . -name "node_modules" -type d -prune -exec rm -rf {} +
rm -f pnpm-lock.yaml

# 重新安装
pnpm install

❌ 问题：VS Code 提示模块找不到

解决：

重启 VS Code
确保使用 pnpm 安装的依赖（不要混用 npm/yarn）
安装 pnpm VS Code 插件

✅ 总结

你现在已完成：

✅ 将 my-space-web 成功迁移到 pnpm monorepo
✅ 实现依赖统一管理、节省磁盘空间
✅ 为未来扩展（如 shared/utils/api）打下基础
✅ 支持一键构建、测试、部署整个项目集

🚀 下一步建议

添加 .gitignore

gitignore 复制代码

node_modules/
dist/
*.log
.DS_Store
pnpm-lock.yaml? # 根据团队规范决定是否提交

配置统一的代码风格

bash 复制代码

# 添加 ESLint + Prettier
pnpm add -D eslint prettier @typescript-eslint/eslint-plugin --filter my-space-web

配置 CI/CD

yaml 复制代码

# .github/workflows/ci.yml
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'pnpm'
  
  - run: pnpm install
  - run: pnpm run build:all

📄 文档结束

如需进一步集成 TypeScript 构建、自动监听 shared 变化、或配置 CI/CD，请随时提出！

pnpm + Monorepo 使用教程（集成 Vue 3 项目）