使用pnpm本地开发测试组件

在使用 pnpm 开发和测试本地组件时，核心思路是利用 pnpm 的工作区（workspace） 和链接（link） 特性，实现组件库与测试项目的无缝联动（修改组件库代码后，测试项目无需重新安装即可实时生效）。以下是完整的实操指南，涵盖单包、多包（monorepo）两种常见场景。

一、前置准备

1. 安装 pnpm（若未安装）：

   npm install -g pnpm
   # 或使用 corepack（推荐，管理包管理器版本）
   corepack enable pnpm
   

2. 确认 pnpm 版本（建议 >= 7.0.0）：

   pnpm -v
   

二、场景 1：单包组件库 + 测试项目（两个独立目录）

适用于组件库是单个包（如 my-ui），测试项目（如 test-app）是另一个独立项目的场景。

步骤 1：目录结构

projects/
├── my-ui/          # 本地组件库（待开发）
│   ├── package.json
│   ├── src/
│   │   └── button.vue  # 示例组件
│   └── dist/          # 打包后的产物（可选）
└── test-app/       # 测试项目（如 Vue/React 项目）
    ├── package.json
    └── src/

步骤 2：初始化组件库（my-ui）

1. 进入组件库目录，初始化 package.json：

   cd my-ui
   pnpm init -y
   

2. 配置组件库的核心字段（关键！确保可被链接和识别）：

   // my-ui/package.json
   {
     "name": "@my-org/my-ui",  // 自定义包名（建议带作用域，避免冲突）
     "version": "1.0.0",
     "main": "dist/index.js",  // 入口文件（若未打包，可指向 src/index.js）
     "module": "dist/index.es.js", // ES 模块入口（可选）
     "type": "module", // 若使用 ESM，需配置
     "files": ["dist", "src"], // 发布时包含的文件（本地测试可忽略）
     "scripts": {
       "dev": "vite build --watch" // 可选：实时打包（修改代码自动更新 dist）
     }
   }
   

3. 编写示例组件（如 Vue 组件）：

   <!-- my-ui/src/button.vue -->
   <template>
     <button class="my-button">{{ text }}</button>
   </template>
   <script setup>
   defineProps({
     text: {
       type: String,
       default: "默认按钮"
     }
   });
   </script>
   

4. 入口文件导出组件：

   // my-ui/src/index.js
   import MyButton from "./button.vue";
   export { MyButton };
   

步骤 3：初始化测试项目（test-app）

以 Vue 项目为例（React/其他框架同理）：

# 新建 Vue 项目
pnpm create vite test-app --template vue
cd test-app
pnpm install

步骤 4：本地链接组件库（核心操作）

pnpm 提供 pnpm link 命令，实现本地包的软链接（替代 npm link，更稳定）。

方式 1：从测试项目链接组件库（推荐）

# 进入 test-app 目录
cd test-app
# 链接本地 my-ui 组件库（绝对路径/相对路径均可）
pnpm link ../my-ui
# 或绝对路径：pnpm link /Users/xxx/projects/my-ui

方式 2：从组件库链接到全局，再从测试项目链接全局包

# 进入 my-ui 目录，链接到 pnpm 全局仓库
cd my-ui
pnpm link --global

# 进入 test-app 目录，链接全局的 @my-org/my-ui
cd test-app
pnpm link --global @my-org/my-ui

步骤 5：在测试项目中使用组件

1. 若组件库未打包（直接用源码），需确保测试项目支持组件格式（如 Vue 的 SFC）：

   // test-app/src/main.js
   import { createApp } from 'vue'
   import { MyButton } from '@my-org/my-ui' // 直接引入组件库源码
   import App from './App.vue'
   
   const app = createApp(App)
   app.component('MyButton', MyButton)
   app.mount('#app')
   

2. 在测试项目的组件中使用：

   <!-- test-app/src/App.vue -->
   <template>
     <MyButton text="本地测试按钮" />
   </template>
   

步骤 6：实时开发测试

1. 若组件库需要打包（如 Rollup/Vite 打包），启动组件库的监听打包：

   # my-ui 目录
   pnpm run dev # 对应 package.json 中的 "dev": "vite build --watch"
   

2. 启动测试项目的开发服务器：

   # test-app 目录
   pnpm run dev
   

3. 修改 my-ui/src/button.vue 的代码，测试项目会实时更新（无需重新安装/链接）。

三、场景 2：Monorepo 架构（组件库 + 测试项目在同一工作区）

若组件库和测试项目属于同一个 Monorepo 项目，推荐使用 pnpm workspace，无需手动 link，更高效。

步骤 1：初始化 Monorepo 项目

1. 目录结构：

   my-monorepo/
   ├── packages/
   │   ├── my-ui/       # 组件库包
   │   │   └── package.json
   │   └── test-app/    # 测试项目包
   │       └── package.json
   └── pnpm-workspace.yaml # pnpm 工作区配置
   

2. 创建 pnpm-workspace.yaml（核心配置）：

   # pnpm-workspace.yaml
   packages:
     - 'packages/**' # 匹配所有 packages 下的子包
   

3. 初始化根目录：

   cd my-monorepo
   pnpm init -y # 可选：根目录生成 package.json
   

步骤 2：配置组件库和测试项目的 package.json

1. 组件库包（packages/my-ui/package.json）：

   {
     "name": "@my-org/my-ui",
     "version": "1.0.0",
     "main": "src/index.js",
     "scripts": {
       "dev": "vite build --watch"
     }
   }
   

2. 测试项目包（packages/test-app/package.json）：

   {
     "name": "@my-org/test-app",
     "version": "1.0.0",
     "dependencies": {
       "@my-org/my-ui": "workspace:*" // 关键：使用 workspace 协议引用本地组件库
     },
     "scripts": {
       "dev": "vite"
     }
   }
   

步骤 3：安装依赖

在 Monorepo 根目录执行安装，pnpm 会自动将 @my-org/my-ui 链接到 test-app 的 node_modules 中：

cd my-monorepo
pnpm install

步骤 4：开发测试

1. 启动组件库的监听打包（若需要）：

   cd packages/my-ui
   pnpm run dev
   

2. 启动测试项目：

   cd packages/test-app
   pnpm run dev
   

3. 修改组件库代码，测试项目实时生效，无需额外操作。

四、关键注意事项

1. 包名一致性：链接时的包名必须与组件库 package.json 中的 name 完全一致（包括作用域，如 @my-org/my-ui）。
2. 入口文件配置：确保组件库的 main/module 字段指向正确的入口文件，否则测试项目会引入失败。
3. 依赖冲突：若组件库和测试项目依赖同一个包（如 Vue），建议在 Monorepo 根目录统一管理依赖（pnpm -w add vue），避免多版本问题。
4. 取消链接：若需取消本地链接，执行：

   # 测试项目目录
   pnpm unlink @my-org/my-ui
   # 或全局取消
   pnpm unlink --global @my-org/my-ui
   

5. TypeScript 支持：若组件库使用 TS，需配置 tsconfig.json 的 declaration: true 生成类型文件，并在 package.json 中配置 types 字段指向类型入口，测试项目可获得类型提示。

五、总结

• 独立项目场景：用 pnpm link 实现本地组件库与测试项目的软链接，实时开发。
• Monorepo 场景：用 pnpm workspace + workspace:* 协议，无需手动 link，更高效。
• 核心优势：pnpm 的链接机制比 npm/yarn 更稳定，且不会产生重复依赖，能精准映射本地组件库代码，大幅提升本地开发测试效率。