---
site: "zyx.tw"
title: "合併前打包，合併後沿用同一份映像檔部署"
description: "用內容辨認映像檔，再讓各專案呼叫共用部署流程。"
url: "https://www.zyx.tw/map/craft/one-way-to-deploy"
---

# 合併前打包，合併後沿用同一份映像檔部署

紀錄 034，深讀 L2，863 字，2 分鐘，v2.0.0，更新 2026-11-16

打包是把程式與執行環境包成映像檔，上線則是讓主機改用新映像檔。在合併前完成打包，合併後只換標籤並上線，就能省去打包等待。

這個做法有一個前提：合併後的程式碼內容沒有改變，才能沿用先前打包的映像檔。

## 先把建置放到合併前

pull request 是修改合併進專案之前的關卡。部署流程在這個階段執行自動檢查，同時把程式與執行環境打包。

打包產生的映像檔，就是後續發布要使用的產物。流程用程式碼內容算出映像檔的標籤，讓合併後的流程能沿用對應內容。

下圖比較兩種安排：差別在於合併後還有哪些工作要完成，以及上線前必須等待什麼。

**在哪個階段打包？ 合併之後**

合併後的工作:
- 打包
- 上線

上線前的條件:
- 等待映像檔打包完成

合併後才開始打包。打包完成後才能上線。

**在哪個階段打包？ pull request 階段**

合併後的工作:
- 替已打包的映像檔換標籤
- 上線

合併前的工作:
- 自動檢查與打包一起執行

自動檢查執行時，也完成打包。合併後使用已打包的映像檔。

## 用 digest 辨認內容，用標籤命名

digest 是由映像檔內容算出的雜湊值，內容相同，digest 就相同。標籤則是指向某個 digest 的名字，可以改指其他映像檔。

合併後重新打包，上線的映像檔可能與測試過的不同；只換標籤時，兩者是同一份內容。

## 發布要包含映像檔與設定

Twelve-Factor App 是把應用的建置、發布與執行分開的做法準則。建置產生映像檔，發布加上設定，執行階段才啟動程式。

示意碼中的 release 把映像檔 digest 與環境設定放在一起，再交給 deploy 部署。每次發布都有新的編號，發布內容不再更動。

這也決定了退回的單位：部署前一次發布，而不是修改目前發布的內容。示意碼在 healthy() 判定不健康時，執行 deploy(previous\_release)。

pull request 階段的共用流程執行 build 產生映像檔，再用 push 送到映像檔儲存處 registry；合併後的流程只做 tag 與 deploy，分別加上標籤與部署發布。

```
digest = build(commit)                  # sha256:..., once
push(registry, digest)

# after merge: no rebuild, only a new name
tag(registry, digest, "sha-" + commit)
release = {"image": digest, "config": config[env]}
deploy(release)

if not healthy():
    deploy(previous_release)            # rollback
```

下圖把這段示意碼拆成互動步驟，呈現映像檔如何經過建置、標記與發布，以及不健康時如何退回前一次發布。

```text
digest = build(commit)                  # sha256:..., once
push(registry, digest)

# after merge: no rebuild, only a new name
tag(registry, digest, "sha-" + commit)
release = {"image": digest, "config": config[env]}
deploy(release)

if not healthy():
    deploy(previous_release)            # rollback
```

Figure: Pseudo code of build once and promote: build an image once and push it by digest, give it a new tag after merge, deploy a release made of the image and the configuration, and roll back to the previous release when it is unhealthy.

1. Build: 每個 commit 只打包 1 次，得到固定的 digest。
2. Tag: 合併後不重新打包，只替同一個 digest 加上新標籤。
3. Release: 發布是映像檔加上環境設定。
4. Rollback: 新版不健康時，改回前一次發布。

## 各專案只接上共用流程

把打包、換標籤與上線寫成共用流程，集中放在同一個專案，供其他專案呼叫。讓程式開發助手 Claude Code 依共用流程的文件設定部署，直接呼叫流程與等待指令。

釋出版本採用固定格式，映像檔標籤則使用程式碼編號。設定後不再改指別的內容，這才是標籤可以信任的條件。

等待指令負責回報部署結果，區分上線成功、失敗與等待逾時。

## 上線後，對照實際行為

上線後，對照線上實際行為，依 怎樣才算完成 確認結果。

## 來源

- [The Twelve-Factor App: Build, release, run](https://12factor.net/build-release-run), 12factor.net
- [OCI Image Format: Content Descriptors](https://github.com/opencontainers/image-spec/blob/main/descriptor.md), Open Container Initiative
- [Release Engineering](https://sre.google/sre-book/release-engineering/), Google SRE Book

## 地圖

- 回到：[習慣](https://www.zyx.tw/map.md)
