想像一下，你是一位大廚，為了讓旗下連鎖餐廳都能做出同樣美味的料理，你研發了一系列「秘密醬汁」。你希望這些醬汁能被分送到各個分店，但又不能讓外面的路人隨便拿走。
在軟體開發的世界裡，這些秘密醬汁就是公司內部的「私有套件」。
當專案多起來後，你一定遇過這種困擾：同一個 UI 元件或工具函式，難道要在每個專案裡複製貼上嗎？或者用 Git Submodule 管理到懷疑人生？其實，你只需要建立一個「私有食材庫（Private NPM Registry）」。今天我們就來聊聊，如何使用 pnpm 將套件發佈到 GitLab，讓團隊成員能像安裝開源套件一樣，簡單一行指令搞定。
為什麼需要私有套件與 Scope？
在 Node.js 的宇宙裡，私有套件必須有一個「姓氏」，這就是 Scope（作用域）。
比如說，你們公司名字叫 @my-company，那套件名字可能就長這樣：@my-company/ui-kit。有了這個姓氏，當 pnpm 看到它時，就不會傻傻跑到公開的 npmjs.org 亂找，而是直接衝去你指定的公司導航座標。
關鍵決策：Group Level vs. Project Level
在 GitLab 裡，這就像是你把調味料放哪：
| 層級 | 說明 |
|---|---|
| Project Level (專案層級) | 像是主廚的私人保險箱，只有特定菜色的人能用。設定起來比較繁瑣，每個套件都要獨立設定。 |
| Group Level (群組層級) | 這就是「中央廚房」的概念，強烈推薦！只要設定一次，同個群組下的幾打甚至幾百個套件，都能共用同一套設定與憑證。 |
設定「通行證」：Access Token 與環境變數
要進入地下糧倉，你得先領一張「門禁卡」。
- 到 GitLab 的 Settings > Access Tokens。
- 申請一個 Token，權限勾選
read_api(下載用) 與write_package_registry(發佈用)。 - 重要： 領到 Token 後，絕對不要直接寫死在程式碼或
.npmrc檔案裡！這就像把金庫鑰匙插在門上。
最專業的做法是把它藏在「環境變數」裡。在你的 Mac 或 Linux 終端機（如 ~/.zshrc）加入這行：
export GITLAB_TOKEN="你的_GitLab_Token"
這樣系統就會自動幫你帶上憑證，安全又方便。
導航設定：.npmrc 的奧義
接著，我們要在專案根目錄建立一張導航地圖 .npmrc，告訴 pnpm 怎麼走：
# 看到 @my-company 開頭的，請去 GitLab 找
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/
# 設定門禁卡認證（讀取我們剛剛設好的環境變數）
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"
只要換上你們公司的 Group ID，這條路就鋪好了！
發佈前的最後一哩路：包裝的藝術
很多人設定完連線就急著發佈，結果一不小心就把測試檔、甚至是秘密設定也一起傳上去了。這時 package.json 的 files 欄位 就派上用場了。
這是一個「白名單」的概念：
{
"name": "@my-company/lib-1",
"files": [
"dist"
],
"publishConfig": {
"registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
}
}
| 設定 | 說明 |
|---|---|
files |
明確告訴系統，我只要發佈 dist 內的編譯精華，其他垃圾都留在原地。 |
publishConfig |
這是雙重保險，確保這個套件絕對不會手滑發佈到公海（npmjs.org）。 |
發佈前，建議用 pnpm pack 指令在本地先開箱檢查一下，確認 package 內容沒問題後，再瀟灑地打下 pnpm publish！
總結
建立私有食材庫並不難，關鍵在於：
- 申請 Token 並妥善用環境變數保護。
- 配置正確的
.npmrc導航地圖。 - 利用
package.json的files欄位做到精準出貨。
學會這套流程，你也能讓公司的程式碼重用變得專業、安全且優雅。現在就去動手打造你們的中央廚房吧！