使用 pnpm link 連結並測試本地 Packages

當你在開發一個 JavaScript 的 library 時，通常需要在實際的專案中測試它。pnpm link 是一個非常有用的工具，它允許你將本地開發的 package 加入到其他專案中，從而方便地進行測試和調試。本文將詳細介紹如何使用 pnpm link，包括其兩種主要的 Link 模式，也會針對部份 pnpm link 的潛在問題作出解說。

Global Link

Global Link 讓你可以將一個 library「發佈」到你的本機 global 環境中，這樣就可以輕鬆地將它加入到任何其他本機專案。

步驟 1：在 Global 環境中「發佈」library

cd ~/projects/my-lib
pnpm link --global

步驟 2：將 Global Link 的 Package 加入到專案

cd ~/projects/my-app
pnpm link --global my-lib

全局取消 Global Link

在系統任何位置執行 pnpm remove --global my-lib 即可取消所有專案與 my-lib 的連結。

個別專案取消 Global Link

如果 my-app 的 package.json 中已包含 my-lib 作為 dependency，可以使用以下命令取消連結：

cd ~/projects/my-app
pnpm i # 還原所有 link
# 或者
pnpm unlink my-lib # 只還原 my-lib 的 link

Global Binary 的問題

值得注意的是，pnpm link 的 Global binary 功能目前存在問題。根據官方文件，pnpm link -g 應支援含有 bin 的 package，允許其在系統任何地方執行該 package 的 binary。但是，自 2022 年 5 月起，有使用者報告該功能在 pnpm 7 中無法正常工作，並且這個問題在最新版本 8.12.1 中依然存在。

因此，如果你的 package 包含 bin 部分，你可能無法通過 link -g 指令讓 package 在系統各處直接運行它的 binary。目前只能將這類 package 加入到指定專案中，並在該專案內執行 binary。

Directory Link

Directory Link 允許你直接將一個本地 package 鏈接到另一個專案，而不是通過 global 環境。

方法一：在目標專案中 link library

# 在 my-app 中 link my-lib
cd ~/projects/my-app
pnpm link ~/projects/my-lib

方法二：從 library 中 link 目標專案

# 在 my-lib 中 link 到 my-app
cd ~/projects/my-lib
pnpm link --dir ~/projects/my-app

取消 Directory Link

無論使用哪種方法一或二進行 Directory link，取消 link 的操作都在目標專案中進行：

# 在 my-app 中取消 link my-lib
cd ~/projects/my-app

pnpm unlink ~/projects/my-lib
# 或者使用 package 名稱
pnpm unlink my-lib

總結

pnpm link 與 npm link 和 yarn link 相似，提供了一種在本地環境中連結 packages 的便捷方式。雖然 pnpm 的官方文檔提供了基本的使用說明，但在實際應用、細節處理，以及特定使用情境下，文檔可能未能詳盡說明。本文旨在彌補這些空缺，為使用 pnpm 的開發者提供更全面的 link 使用細節。

目前，pnpm link 的某些功能，如 Global binary，還存在一些問題。這些問題的存在可能會對依賴於特定功能的開發者造成一定的不便。隨著 pnpm 的不斷更新和改進，我們期待這些問題將在未來的版本中得到解決。

隨著 pnpm 的不斷進化，本文將會適時更新以提供最新信息，希望能協助 pnpm 開發者實現更高效的開發流程。