Package on Tarragonhttps://tarrragon.github.io/blog/tags/package/Recent content in Package on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Wed, 06 May 2026 00:00:00 +0000Package / Library Release CI/CDhttps://tarrragon.github.io/blog/ci/package-library-release/Wed, 06 May 2026 00:00:00 +0000https://tarrragon.github.io/blog/ci/package-library-release/<p>Package / Library Release CI/CD 的核心責任是把可重用套件安全發佈到分發平台，並維持版本語意與相容承諾。它和應用部署不同，重點在版本管理、相容邊界、發佈簽章與撤版策略。</p> <h2 id="場域定位">場域定位</h2> <p>套件發佈常見於 NPM、PyPI、Maven、Crates 等生態。發布後會被多個下游專案依賴，因此每次 release 都是公共契約變更。</p> <table> <thead> <tr> <th>面向</th> <th>Package release 常見責任</th> <th>判讀訊號</th> </tr> </thead> <tbody> <tr> <td>Build</td> <td>package artifact、metadata、lock input</td> <td>產物是否可重現</td> </tr> <tr> <td>Validation</td> <td>API/ABI 相容性、smoke test、publish dry-run</td> <td>破壞性變更是否被識別</td> </tr> <tr> <td>Versioning</td> <td>semver、pre-release、changelog</td> <td>版本語意是否與變更一致</td> </tr> <tr> <td>Publish</td> <td>registry token、scope、provenance</td> <td>發版是否可追溯且權限正確</td> </tr> <tr> <td>Recovery</td> <td>yank/deprecate/hotfix release</td> <td>事故時是否可快速止損</td> </tr> </tbody> </table> <h2 id="release-發布類型分類">Release 發布類型分類</h2> <p>「發版」在中文討論裡常被當成單一動作，但實際上有五條互不重疊的通道，每條的觸發條件、產物形式、下游取用方式都不一樣。下游使用者讀 README 時若沒分清楚自己在走哪條通道，很容易踩到「文件寫了安裝指令，但對應通道還沒被建立」的情況。</p> <table> <thead> <tr> <th>類型</th> <th>產物形式</th> <th>下游取用方式</th> <th>典型觸發</th> <th>代表生態</th> </tr> </thead> <tbody> <tr> <td>Source release</td> <td>git tag + tarball</td> <td><code>git clone</code> 或 <code>go install</code> 後編譯</td> <td>tag push</td> <td>Go module、許多 OSS 函式庫</td> </tr> <tr> <td>Registry publish</td> <td>套件清單登錄</td> <td><code>npm install</code> / <code>pip install</code> 等</td> <td><code>publish</code> 指令</td> <td>npm、PyPI、crates.io、Maven</td> </tr> <tr> <td>Binary release</td> <td>預編譯多平台執行檔，掛在 GitHub Release</td> <td>下載 binary 或 installer script</td> <td>tag push</td> <td>cargo-dist、goreleaser 工具鏈</td> </tr> <tr> <td>Container image</td> <td>OCI image</td> <td><code>docker pull</code> / k8s manifest</td> <td>tag 或 commit</td> <td>Docker Hub、GHCR、ECR</td> </tr> <tr> <td>OS package</td> <td><code>.deb</code> / <code>.rpm</code> / Homebrew formula</td> <td>套件管理器 install</td> <td>上游同步</td> <td>apt、yum、Homebrew、winget</td> </tr> </tbody> </table> <p>這五類常常組合出現（例如同時推 source、registry、binary release）。組合愈多、上游維護成本愈高，但下游能用的入口也愈廣。判讀訊號：</p> <ul> <li>README 寫的是 <code>pip install x</code> → 屬 registry，去 PyPI 確認版本</li> <li>README 寫的是 <code>curl ... /releases/latest/download/...sh | sh</code> → 屬 binary release + installer，去 GitHub Releases 確認 asset 存在</li> <li>README 寫的是 <code>git clone</code> 後 <code>make</code> → 只走 source，沒任何打包通道</li> <li>README 寫的是 <code>docker pull ghcr.io/...</code> → 屬 container image，去 registry 確認 tag</li> </ul> <h2 id="常見注意事項">常見注意事項</h2> <ul> <li>發版前要明確區分 breaking / feature / fix，避免版本語意錯置。</li> <li>發版流程應固定化（tag 規則、changelog 來源、artifact provenance）。</li> <li>對外 SDK 要維持 contract 測試，避免下游升級破壞。</li> <li>套件來源與 token 權限要最小化，並定期輪替。</li> <li>README 安裝段落寫的通道，發版前要實際跑過一次 — 「workflow 寫好」不代表「通道已上線」。</li> </ul> <h2 id="安裝路徑分層">安裝路徑分層</h2> <p>Package release 的文件建議同時提供兩條安裝路徑，讓不同風險場景有對應入口。</p> <table> <thead> <tr> <th>路徑類型</th> <th>目標讀者</th> <th>流程</th> <th>風險控制</th> <th></th> </tr> </thead> <tbody> <tr> <td>快速路徑</td> <td>本機快速試用、低風險場景</td> <td>一行安裝命令（例如 `curl &hellip;</td> <td>sh`）</td> <td>速度優先，依賴上游發布品質</td> </tr> <tr> <td>可審計路徑</td> <td>生產環境、受管設備、合規場景</td> <td>下載產物 → 驗證 checksum/provenance → 執行</td> <td>可追溯、可驗證、可稽核</td> <td></td> </tr> </tbody> </table> <p>這個分層能避免單一路徑綁死全部使用者。上游維護者要確保兩條路徑都可用，且文件清楚標示使用時機。可審計路徑的具體範例可直接沿用 <a href="binary-release-and-installer/">Binary release 與 installer 模式</a> 的最小安全基線。</p>Package / Library Release CI/CD 的核心責任是把可重用套件安全發佈到分發平台，並維持版本語意與相容承諾。它和應用部署不同，重點在版本管理、相容邊界、發佈簽章與撤版策略。

場域定位

套件發佈常見於 NPM、PyPI、Maven、Crates 等生態。發布後會被多個下游專案依賴，因此每次 release 都是公共契約變更。

面向 Package release 常見責任 判讀訊號
Build package artifact、metadata、lock input 產物是否可重現
Validation API/ABI 相容性、smoke test、publish dry-run 破壞性變更是否被識別
Versioning semver、pre-release、changelog 版本語意是否與變更一致
Publish registry token、scope、provenance 發版是否可追溯且權限正確
Recovery yank/deprecate/hotfix release 事故時是否可快速止損

Release 發布類型分類

「發版」在中文討論裡常被當成單一動作，但實際上有五條互不重疊的通道，每條的觸發條件、產物形式、下游取用方式都不一樣。下游使用者讀 README 時若沒分清楚自己在走哪條通道，很容易踩到「文件寫了安裝指令，但對應通道還沒被建立」的情況。

類型 產物形式 下游取用方式 典型觸發 代表生態
Source release git tag + tarball git clone 或 go install 後編譯 tag push Go module、許多 OSS 函式庫
Registry publish 套件清單登錄 npm install / pip install 等 publish 指令 npm、PyPI、crates.io、Maven
Binary release 預編譯多平台執行檔，掛在 GitHub Release 下載 binary 或 installer script tag push cargo-dist、goreleaser 工具鏈
Container image OCI image docker pull / k8s manifest tag 或 commit Docker Hub、GHCR、ECR
OS package .deb / .rpm / Homebrew formula 套件管理器 install 上游同步 apt、yum、Homebrew、winget

這五類常常組合出現（例如同時推 source、registry、binary release）。組合愈多、上游維護成本愈高，但下游能用的入口也愈廣。判讀訊號：

  • README 寫的是 pip install x → 屬 registry，去 PyPI 確認版本
  • README 寫的是 curl ... /releases/latest/download/...sh | sh → 屬 binary release + installer，去 GitHub Releases 確認 asset 存在
  • README 寫的是 git clone 後 make → 只走 source，沒任何打包通道
  • README 寫的是 docker pull ghcr.io/... → 屬 container image，去 registry 確認 tag

常見注意事項

  • 發版前要明確區分 breaking / feature / fix，避免版本語意錯置。
  • 發版流程應固定化（tag 規則、changelog 來源、artifact provenance）。
  • 對外 SDK 要維持 contract 測試，避免下游升級破壞。
  • 套件來源與 token 權限要最小化，並定期輪替。
  • README 安裝段落寫的通道，發版前要實際跑過一次 — 「workflow 寫好」不代表「通道已上線」。

安裝路徑分層

Package release 的文件建議同時提供兩條安裝路徑，讓不同風險場景有對應入口。

路徑類型 目標讀者 流程 風險控制
快速路徑 本機快速試用、低風險場景 一行安裝命令（例如 `curl … sh`） 速度優先，依賴上游發布品質
可審計路徑 生產環境、受管設備、合規場景 下載產物 → 驗證 checksum/provenance → 執行 可追溯、可驗證、可稽核

這個分層能避免單一路徑綁死全部使用者。上游維護者要確保兩條路徑都可用，且文件清楚標示使用時機。可審計路徑的具體範例可直接沿用 Binary release 與 installer 模式 的最小安全基線。

學習路線

章節 主題 核心責任
Binary release 與 installer 模式 Tag-driven binary release GitHub Release + cargo-dist / goreleaser 的發版鏈路

下一步路由

]]>