前言

在前兩天，我們已經討論了 Monorepo 與 Angular Library，並學習如何建立共用的元件函式庫。
今天，我們要進一步探討 Library 的版本管理，以及如何透過 Verdaccio 建立一個公司內部的私有套件管理平台，來確保團隊順暢的開發流程。

為什麼需要版本管理？

當專案越來越大時，Library 的維護就會變得複雜。如果沒有良好的版本策略，很容易出現以下情況：

• 新專案需要最新功能，但老專案卻被迫升級，導致破壞相容性。
• 同一個元件在不同專案中出現「多個版本」，最終變得難以追蹤。
• 沒有明確版本號，團隊成員無法判斷到底該用哪個版本。

這就是為什麼要引入 Semantic Versioning (語意化版本號, SemVer)。

Semantic Versioning（語意化版本）

通常版本號會遵守 SemVer 規範：

主版號(Major).次版號(Minor).修訂號(Patch)

• Major (X.0.0)：有破壞性改動（breaking change）
• Minor (0.X.0)：新增功能，向下相容
• Patch (0.0.X)：修 bug，向下相容

例如：

• 1.0.0 → 初始穩定版本
• 1.1.0 → 新增功能（仍相容）
• 1.1.1 → 修正 bug
• 2.0.0 → 發生不相容改動

在 package.json 中，會透過版本號範圍來指定可接受的版本：

• "^1.2.3" → 允許更新 Minor 與 Patch（例如 1.5.0、1.2.9）
• "~1.2.3" → 只允許更新 Patch（例如 1.2.4，但不會到 1.3.0）

為什麼要用私有套件倉庫？

假設我們已經建立好 @my-company/my-lib，如果直接 npm publish 到公開 npm registry，任何人都能安裝，這對公司內部專案顯然不合適。

因此我們需要一個 私有套件管理機制，讓套件只在公司或團隊內部流通。這時候 Verdaccio 就派上用場。

適用場景：

• 公司內部共用套件（UI Library、工具函式庫、Service SDK）
• 不希望將程式碼公開到 npm
• 測試發佈流程（不影響正式 npm 環境）

Verdaccio 簡介

Verdaccio 是一個輕量級的私有 npm registry：

• 🚀 快速上手：一行指令即可啟動，不需要額外資料庫。
• 🔐 權限控管：可以設定哪些使用者能發佈或下載套件。
• 💾 快取代理：會自動代理 npm 官方 registry，讓團隊加速安裝。
• 🛠 支援 CI/CD：可與 Jenkins、GitHub Actions 等整合，達成自動發佈。

安裝與啟動 Verdaccio

在本機或伺服器上執行：

npm install -g verdaccio

# 啟動 Verdaccio
verdaccio

預設會開在 http://localhost:4873，並提供一個 Web UI，可以檢視與管理套件。

發佈 Library 到 Verdaccio

假設我們已經在 dist/my-lib/ 下有建置結果，就可以發布到私有雲上，請記得要啟動 Verdaccio 才能使用喔！

cd dist/my-lib

# 登入 Verdaccio
npm adduser --registry http://localhost:4873/

# 發佈套件
npm publish --registry http://localhost:4873/

專案中使用 Library

在其他應用專案中，只需設定 npm registry 並安裝套件，請記得要啟動 Verdaccio 才能使用喔！容易踩雷再說一次。

npm set registry http://localhost:4873

npm install @my-company/my-lib

即可像使用一般 npm 套件一樣引用：

import { MyButtonComponent } from '@my-company/my-lib'

不過如果只是單純測試的話，之後記得改回原本的 npm 位置 ，或是改成 npm install @my-company/my-lib --registry 私有雲位置 來下載，才不會忘記自己設過什麼，出了問題比較好追蹤。

# 恢復預設 npm registry
npm set registry https://registry.npmjs.org/

小結

從 Day 28 Monorepo 到 Day 29 Angular Library，再到今天的 Day 30 Verdaccio 私有套件管理，我們完成了一條完整的前端共用元件生命週期：

1. 集中管理程式碼（Monorepo）
2. 抽離可重用元件（Library）
3. 透過版本與私有倉庫發佈（Verdaccio）

這樣一來，不論團隊規模多大，都能保持 一致性、可維護性與安全性。

未來若要延伸學習，可以進一步往這些方向：

• 自動化版本號產生（semantic-release）
• Changelog 自動生成
• 多套件 Monorepo 發佈（Nx / Lerna）：像是 Angular Material 、Ant Design

本系列就先告一段落，希望這 30 天的內容對大家工作上有幫助。