乐闻世界logo
6月2日 01:41

npm link 怎么用？本地包开发链接和常见坑

npm link 让你在本地开发时把一个包"链接"到另一个项目，改了代码立即生效，不用反复 npm publish + npm install。

工作原理

npm link 分两步：

第一步：在要开发的包目录里执行 npm link，把当前包注册到全局 node_modules。

bash
cd ~/projects/my-ui-lib
npm link
# 把 my-ui-lib 链接到 /usr/local/lib/node_modules/my-ui-lib

第二步：在使用这个包的项目里执行 npm link my-ui-lib，创建一个符号链接。

bash
cd ~/projects/my-app
npm link my-ui-lib
# node_modules/my-ui-lib -> /usr/local/lib/node_modules/my-ui-lib -> ~/projects/my-ui-lib

本质就是创建符号链接（symlink）。修改 my-ui-lib 的代码，my-app 里立即生效，不用重新安装。

实际使用场景

1. 开发组件库

你在开发一个 UI 组件库，同时在业务项目里使用它。用 npm link 把组件库链接到业务项目，改组件代码后业务项目自动更新。

2. 开发 CLI 工具

CLI 工具通常全局安装测试。npm link 在全局注册你的 CLI，修改代码后直接运行最新版本。

3. 修复第三方包的 bug

fork 一个包，本地修改后 link 到项目里验证修复。确认无误后再提 PR。

常见问题

1. 多个包互相依赖

monorepo 里 A 依赖 B，B 也依赖 A？用 npm link 双向链接：先在 B 目录 npm link，再去 A 目录 npm link B；然后在 A 目录 npm link，再去 B 目录 npm link A。

更好的方案：用 workspace（npm 7+ 的 workspaces）替代 npm link，自动处理内部依赖。

2. React 双实例问题

组件库和业务项目各有一份 React 实例，导致 Hooks 报错 "Invalid hook call"。解决：在业务项目里 link React 到组件库。

bash
cd ~/projects/my-app/node_modules/react
npm link
cd ~/projects/my-ui-lib
npm link react

这样两个项目共用同一份 React。

3. link 后 publish 会把符号链接打包

npm link 创建的是符号链接，npm publish 时可能把链接路径打包进去。发布前务必 npm unlink 确保包内容正确。

4. npm unlink 清除链接

bash
cd ~/projects/my-app
npm unlink my-ui-lib    # 在项目里取消链接
npm install my-ui-lib   # 重新安装正式版本

cd ~/projects/my-ui-lib
npm unlink              # 取消全局注册

替代方案

  • npm workspaces：monorepo 场景首选，不需要 link，npm 自动处理内部包的符号链接
  • yalc：把包发布到本地仓库（不是全局 node_modules），比 link 更稳定，不受全局污染影响
  • pnpm link：pnpm 的 link 命令，行为类似但更严格
标签：NPM