如何在 Node.js 的 中使用本地套件

README.md

如何在 Node.js 的 package.json 中使用本地套件

在 Node.js 專案開發中，有時您會需要使用本地開發中的套件版本，而不是從 npm 註冊表安裝的公開版本。這在以下情況特別有用：

• 您正在開發一個新的套件，並希望在另一個專案中測試它。
• 您正在修復一個套件中的錯誤，並希望在您的專案中驗證修復。
• 您需要對現有套件進行客製化修改，並在您的專案中使用該修改版本。

以下是幾種將 package.json 中的套件指向本地版本的方法：

方法一：使用 file: 協定

這是最直接且簡單的方法，允許您直接指向本地檔案系統中的套件路徑。當您執行 npm install 或 yarn install 時，npm/yarn 會將該本地套件複製到 node_modules 中。

優點：

• 設定簡單，易於理解。
• 不需要額外的連結步驟。

缺點：

• 不會建立符號連結（symlink），而是複製套件。這意味著如果您修改了本地套件的原始碼，您需要重新執行 npm install 或 yarn install 才能讓變更生效。
• 不適用於需要頻繁修改本地套件並立即看到效果的開發場景。

使用方式：

在您的 package.json 中，將套件版本指向本地路徑：

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "my-local-package": "file:../path/to/my-local-package"
  }
}

請確保路徑是相對於您的專案根目錄的正確路徑。您可以使用相對路徑或絕對路徑。

方法二：使用 npm link 或 yarn link (推薦用於開發)

npm link 和 yarn link 是用於在本地開發環境中建立符號連結的強大工具。它們允許您將本地套件的原始碼直接連結到您的專案的 node_modules 中，這樣您對本地套件的任何修改都會立即反映在您的專案中，無需重新安裝。

優點：

• 建立符號連結，實現即時修改同步。
• 非常適合在開發過程中同時修改主專案和本地套件。

缺點：

• 需要手動連結和解除連結。
• 在某些環境（例如 Docker 容器或 CI/CD 環境）中可能會有權限或路徑問題。

使用方式：

假設您有兩個專案：my-local-package (您正在開發的套件) 和 my-app (使用該套件的專案)。

1. 在本地套件目錄中執行連結命令： 進入 my-local-package 的根目錄，執行：

   cd /path/to/my-local-package
   npm link
   # 或者使用 yarn
   # yarn link

   這會將 my-local-package 註冊為一個全域連結。

2. 在您的專案目錄中連結套件： 進入 my-app 的根目錄，執行：

   cd /path/to/my-app
   npm link my-local-package
   # 或者使用 yarn
   # yarn link my-local-package

   這會在 my-app/node_modules 中為 my-local-package 建立一個符號連結，指向您本地的 my-local-package 原始碼。

解除連結：

當您不再需要使用本地連結時，可以在 my-app 目錄中執行：

cd /path/to/my-app
npm unlink my-local-package
# 或者使用 yarn
# yarn unlink my-local-package

然後在 my-local-package 目錄中執行：

cd /path/to/my-local-package
npm unlink
# 或者使用 yarn
# yarn unlink

方法三：使用 npm pack 和本地 tarball

npm pack 命令會將您的套件打包成一個 .tgz 檔案，就像它會被發佈到 npm 註冊表一樣。然後您可以將這個本地的 .tgz 檔案作為依賴項安裝到您的專案中。

優點：

• 模擬了從 npm 註冊表安裝的行為，確保了套件的完整性。
• 適用於測試特定版本的套件，或者在沒有網路連接的情況下分享套件。

缺點：

• 每次修改本地套件後，都需要重新打包 (npm pack) 並重新安裝 (npm install <tarball>)。
• 不適合頻繁修改的開發場景。

使用方式：

1. 在本地套件目錄中打包： 進入 my-local-package 的根目錄，執行：

   cd /path/to/my-local-package
   npm pack

   這會在當前目錄下生成一個類似 my-local-package-1.0.0.tgz 的檔案。

2. 在您的專案目錄中安裝 tarball： 將生成的 .tgz 檔案複製到您的 my-app 專案中（例如，複製到專案根目錄或一個 packages 資料夾中），然後在 my-app 的 package.json 中指向它：

   {
     "name": "my-app",
     "version": "1.0.0",
     "dependencies": {
       "my-local-package": "file:./my-local-package-1.0.0.tgz"
     }
   }

   然後執行 npm install 或 yarn install。

方法四：使用本地 Git 儲存庫 (如果適用)

如果您的本地套件是一個 Git 儲存庫，您可以直接在 package.json 中指向該本地儲存庫的路徑。npm/yarn 會將該儲存庫複製到 node_modules 中。

優點：

• 可以利用 Git 的版本控制功能。
• 對於在本地有多個相關專案且都由 Git 管理的情況可能有用。

缺點：

• 與 file: 協定類似，不會建立符號連結，而是複製儲存庫。每次修改後需要重新安裝。
• 對於簡單的本地測試可能過於複雜。

使用方式：

在您的 package.json 中，將套件版本指向本地 Git 儲存庫的路徑：

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "my-local-package": "git+file:///path/to/my-local-package"
  }
}

請注意 git+file:// 協定。對於 Windows 系統，路徑可能需要使用三個斜線 file:///C:/path/to/my-local-package。

最佳實踐與考量

• 開發階段： 對於需要頻繁修改本地套件並立即看到效果的開發工作，強烈推薦使用 npm link 或 yarn link。
• 測試或分享： 如果您需要測試特定版本的本地套件，或者在沒有網路的情況下分享套件，npm pack 是一個不錯的選擇。
• 簡單複製： 如果您只是想簡單地將本地套件複製到 node_modules 中，並且不介意每次修改後重新安裝，可以使用 file: 協定。
• CI/CD 環境： 在 CI/CD 環境中，通常不建議使用 npm link，因為它依賴於本地檔案系統的符號連結。此時，file: 協定或將本地套件發佈到一個私有 npm 註冊表（如果有的話）會是更好的選擇。
• 版本控制： 確保您的本地套件有良好的版本控制，無論您使用哪種方法，這都有助於管理依賴。
• 恢復到公開版本： 當您完成本地測試後，請記得將 package.json 中的依賴項恢復到公開的 npm 版本，以避免在生產環境中出現問題。

選擇哪種方法取決於您的具體需求和工作流程。在大多數本地開發場景中，npm link 提供最佳的開發體驗。