npm 开发库 本地测试的几种方案

[npm 包上传机制] 详见 npm 包上传机制

Q: 使用 npm 开发一个组件库 但是每次都需要上传 然后 install 这样改下 就要下载重新测试 极其麻烦

✅ 总结

方法	是否需要发布	实时性	推荐度
npm publish + install	✅ 需要	❌ 差	⭐☆☆☆☆
npm link	❌ 不需要	✅ 好	⭐⭐⭐⭐☆
yalc	❌ 不需要	✅ 好	⭐⭐⭐⭐☆
pnpm workspace	❌ 不需要	✅ 最佳	⭐⭐⭐⭐⭐

---

---

1. npm link（最原生，最常用）

📌 原理

npm link 利用操作系统的 符号链接（symlink），将你本地的组件库项目“链接”到另一个项目的 node_modules 中，就像真的安装了一样。

🔧 使用步骤

步骤 1：在组件库项目中注册为可链接

cd your-component-lib
npm link

这会把你的库注册到全局的 npm 链接列表中（类似全局安装了一个软链接）。

步骤 2：在测试项目中链接该库

cd your-test-app
npm link your-component-lib-name

your-component-lib-name 是组件库 package.json 中的 name 字段。

✅ 完成

现在 your-test-app/node_modules/your-component-lib-name 是一个指向你本地组件库的软链接。

---

✅ 优点

• 原生支持，无需额外工具。
• 实时生效：组件库修改后，只要构建完成，测试项目就能看到变化（配合 --watch 模式更佳）。
• 适合快速验证。

❌ 缺点

• Node Modules 双重解析问题：如果组件库和测试项目依赖了不同版本的 React/Vue，可能导致 Invalid Hook Call 等错误。
• 权限问题：在某些系统（如 Windows）或 Docker 环境中，创建软链接可能需要管理员权限。
• 调试路径混乱：IDE 可能跳转到 node_modules 的链接，而不是源码。
• 不能模拟真实的 npm install 行为（比如 files 字段过滤）。

---

🛠️ 最佳实践

• 组件库使用 npm run build --watch 监听构建。
• 测试项目使用 npm start 启动开发服务器。
• 修改组件 → 自动构建 → 测试项目热更新。

---

2. yalc（现代替代方案）

实际上使用的是 file 协议 file 协议

📌 原理

yalc 模拟了 npm install 的行为，但它从本地文件系统复制构建后的文件到测试项目的 .yalc/ 目录，并修改 package.json 和 node_modules，不使用软链接。

🔧 安装与使用

安装 yalc

npm install -g yalc

步骤 1：在组件库中“发布”到本地仓库

cd your-component-lib
# 先构建（确保 dist 存在）
npm run build
# 推送到 yalc 本地仓库
yalc push

yalc push 会把 dist/ 或 lib/ 等打包后的文件复制到 ~/.yalc/。

步骤 2：在测试项目中“安装”

cd your-test-app
yalc add your-component-lib-name

这会：

• 在 package.json 中添加 "your-component-lib-name": "file:.yalc/your-component-lib-name"
• 把文件复制到 .yalc/your-component-lib-name
• 创建 node_modules 链接

✅ 完成

现在你可以像使用 npm 包一样使用它。

更新组件库后

# 在组件库中修改并重新构建
npm run build
yalc push  # 推送更新

在测试项目中：

yalc update your-component-lib-name

---

✅ 优点

• 不依赖软链接，避免权限问题。
• 更接近真实 npm install 的行为（只复制 files 字段指定的文件）。
• 支持版本管理（yalc push --version 1.0.1）。
• 可以同时测试多个版本。

❌ 缺点

• 需要手动 push 和 update，不是完全实时。
• 多了一层 .yalc 目录，项目略显复杂。
• 需要全局安装 yalc。

---

🎯 适用场景

• 你希望更真实地模拟 npm install。
• 你在 Windows 或 Docker 中遇到 npm link 权限问题。
• 你需要测试多个版本的组件库。

---

3. pnpm workspace（最推荐的长期方案）

📌 原理

pnpm 支持 workspace（工作区），允许你在一个 monorepo 中管理多个包。你可以把组件库和测试项目放在同一个 workspace 中，pnpm 会自动用软链接连接它们。

📁 项目结构示例

my-monorepo/
├── package.json        # 根目录，定义 workspace
├── pnpm-workspace.yaml
├── packages/
│   ├── component-lib/  # 组件库
│   └── demo-app/       # 测试项目

🔧 配置步骤

1. 根目录 package.json

{
  "private": true,
  "workspaces": ["packages/*"]
}

2. 根目录 pnpm-workspace.yaml

packages:
  - "packages/*"

3. 在 demo-app/package.json 中添加依赖

{
  "dependencies": {
    "component-lib": "*"
  }
}

4. 安装依赖

cd my-monorepo
pnpm install

pnpm 会自动识别 workspace 内的包，并创建软链接。

---

✅ 优点

• 完全自动化：安装、链接、更新都由 pnpm 管理。
• 支持多包管理：适合未来扩展更多组件或工具。
• 性能好：pnpm 使用硬链接 + 内容寻址，节省磁盘空间。
• 生态完善：可与 Turborepo、Nx 等工具集成，实现任务调度（如 build、test）。

❌ 缺点

• 需要切换到 pnpm 包管理器（如果你原来用 npm 或 yarn）。
• 初期配置稍复杂。
• 团队协作需要统一使用 pnpm。

---

🎯 适用场景

• 你计划长期维护组件库，甚至发展为 UI 库、设计系统。
• 你有多个相关项目需要联动开发。
• 你追求最佳开发体验和工程化规范。

---

🏁 建议

• 临时测试 / 快速验证 → 用 npm link
• 遇到 link 问题 / 想更真实模拟 install → 用 yalc
• 长期开发 / 团队项目 / 构建组件体系 → 用 pnpm workspace

---