Skip to main content

npm link

在開發本地 NPM 套件時，npm link 是一個非常方便的工具，它可以讓你在不發布套件的情況下，快速在另一個專案中測試它。以下是使用情境與完整的操作流程。

✨ 使用情境​

假設你正在開發一個本地套件 @thomas/lib，並且你有另一個專案（例如 my-app）想要使用這個套件來測試功能。

🔗 建立連結（Link 套件）​

1️⃣ 在套件資料夾內執行：​

npm link

這個動作會將 @thomas/lib 註冊為全域的 symbolic link。

2️⃣ 在你想使用這個套件的專案中執行：

npm link @thomas/lib

這會在 node_modules 中建立一個指向你本地套件的 symbolic link。

🔁 套件有修改，想重新 link？

通常，因為是 symbolic link，修改原始碼後立即會反映到使用端。但如果你想「乾淨重建」，可以按照以下步驟操作：

在套件目錄中（@thomas/lib）：

npm unlink -g
npm link

在使用端專案中（例如 my-app）：

npm unlink @thomas/lib
npm link @thomas/lib

🧹 移除連結（Unlink）

如果你想移除這個 symbolic link，可以這樣操作：

移除全域的 link：

npm unlink -g @thomas/lib

移除專案中的 link（選擇性）：

npm unlink @thomas/lib

常見問題 & 小技巧

  • 有些 bundler（例如 Vite/Webpack）不會偵測到 symbolic link 變更，建議修改後重新啟動開發伺服器。
  • 如果出現奇怪的 module resolution 問題，可以試試加上 --legacy-peer-deps。
  • 如果還是遇到問題，可試著刪除 node_modules 和 package-lock.json，重新安裝：
rm -rf node_modules package-lock.json
npm install
需要特別小心的地方
  1. 在 link 的時候 node 的 version 一定要同步，
  2. lib 需要 npm run build 過才可以 link
  3. npm unlink --no-save [LIN_NAME] 這樣子才不會把 package delete

下面是參考流程