本地如何使用 yarn link 调试本地 npm 包

如何使用 yarn link 调试本地 npm 包：

在前端开发中，通常我们会开发并使用许多 npm 包来实现项目的功能。随着开发的深入，我们经常需要调试或修改某些 npm 包的源码。如果你正在开发一个 npm 包，并且希望在本地项目中进行调试，yarn link 是一个非常强大的工具，它可以帮助你在本地链接并调试 npm 包，而无需每次都发布到 npm 仓库。

1. 为什么要使用 yarn link？

在传统的开发流程中，当你在开发一个 npm 包时，如果想在另一个项目中使用这个包，通常需要做以下几件事：

1. 发布包到 npm：每次你修改了本地包的代码，都需要发布到 npm，然后在项目中更新包的版本。
2. 使用 npm install 或 yarn add：每次修改后，都要在项目中重新执行 npm install 或 yarn add 来获取最新的包版本。

但是，如果你正在开发一个 npm 包并且需要频繁测试，发布到 npm 变得非常繁琐。此时，yarn link 提供了一种便捷的解决方案，它允许你在本地项目中链接并调试 npm 包，而无需发布到 npm 仓库。

2. 什么是 yarn link？

yarn link 是一个本地开发工具，它允许你将本地开发的 npm 包链接到其他项目中进行调试和测试，而不需要每次都发布和安装。具体来说：

• yarn link：在你本地的 npm 包目录中运行，注册你的包作为全局链接。
• yarn link <package-name>：在目标项目中运行，将本地包链接到目标项目的 node_modules 中。

通过 yarn link，你可以在本地开发和调试 npm 包时，实时更新和测试修改的包，而无需发布包或手动重新安装。

3. yarn link 使用流程

步骤 1：在本地包中使用 yarn link

1. 首先，进入你的本地包目录。假设你的包名是 open-app，并且它的代码存放在本地路径 /path/to/your/local/open-app。

   cd /path/to/your/local/open-app
   

2. 在本地包的根目录中运行以下命令，将包注册为全局链接：

   yarn link
   

   执行完后，终端会输出类似如下的信息：

   success Registered "open-app"
   

   这表明你的包已经成功注册为全局链接，可以在其他项目中进行引用。

步骤 2：在目标项目中使用 yarn link

1. 接下来，进入你要调试的目标项目目录。假设你的项目是一个 Vue 项目，位于 /path/to/your/vue-project。

   cd /path/to/your/vue-project
   

2. 在目标项目中运行以下命令，将本地开发包链接到 node_modules 中：

   yarn link "open-app"
   

3. 现在，目标项目就会使用你本地的 open-app 包，而不是从 npm 上下载的版本。你可以像平常一样导入并使用这个包：

   import { openApp } from 'open-app';
   

⚠️ 你的目标项目package.json中不能再有open-app的依赖了，不然还是指向线上npm，删掉后重新yanr install

步骤 3：调试与修改本地包

• 一旦你成功链接了本地包，你就可以在 open-app 包的代码中进行修改并立即查看效果。你不需要重新发布或重新安装包，只要修改本地包的代码，Vue 项目会自动使用最新版本的本地包。
• 如果你修改了本地包的代码，Vue 项目中使用到该包的地方会立刻反映出修改的结果。如果没有看到变化,可能需要构建本地的npm项目。 例如： yarn build

步骤 4：取消链接（如果需要）

如果你不再需要本地链接，可以使用以下命令取消链接：

1. 在目标项目中运行：

   yarn unlink "@meitu/open-app"
   

2. 然后在本地包目录中解除全局链接：

   yarn unlink
   

4. 注意事项

虽然 yarn link 是一个非常方便的工具，但在使用时也有一些注意事项需要了解：

1. 包名必须匹配

确保你在 yarn link 时使用的包名与目标项目中引用的包名一致。例如，你在本地包中使用的是 open-app，那么在目标项目中也需要使用相同的包名来导入它：

import { openApp } from 'open-app';

如果包名不一致，即使成功链接了本地包，目标项目也会找不到该包。yarn link成功的话，在目标项目的node_modules可以找到你 link的 open-app

2. 缓存问题

有时，Yarn 或 npm 会缓存包的内容，导致本地包的修改没有生效。如果你发现修改没有立即反映到目标项目中，可以尝试清除缓存：

yarn cache clean

然后重新安装依赖：

yarn install

3. 版本冲突

yarn link 可能会导致不同版本的包之间出现冲突。如果你的项目或本地包依赖于某个版本的第三方库，确保本地包和目标项目的依赖版本一致。如果依赖冲突，可能会导致运行时错误或不可预期的行为。

4. 不要把本地链接的包提交到代码库

本地链接的包只是开发环境中的临时链接，通常不应该被提交到代码库。如果使用了 yarn link，确保在 .gitignore 中忽略 node_modules 目录，避免将链接的包提交到版本控制系统中。

5. 使用 yarn link 的常见问题及解决方法

问题 1：目标项目中的包版本不更新

原因：可能是目标项目中仍然引用的是缓存的旧版本包。

解决方案：

• 清除 Yarn 缓存：yarn cache clean
• 删除并重新安装依赖：rm -rf node_modules && yarn install
• 确保在本地包的修改后重新构建（如果有构建步骤），例如，如果使用 TypeScript 或 Babel 编译本地包，记得重新编译。

问题 2：链接的包无法正确找到

原因：可能是包名不一致，或者没有正确链接。

解决方案：

• 确保在本地包和目标项目中使用相同的包名。
• 确认 yarn link 是否在正确的包目录中执行，并且 node_modules 目录中确实包含了正确的符号链接。

6. 其他 yarn link 的使用场景

除了调试本地 npm 包外，yarn link 还可以用于以下场景：

• 开发私有 npm 包：如果你开发的是私有 npm 包，使用 yarn link 可以在多个项目之间共享和调试该包，而无需发布到 npm。
• 本地组件库开发：如果你在开发组件库，并且希望实时调试组件库的修改，yarn link 可以帮助你在不同的项目中链接并使用该组件库。