對於 CI 模板和修復管道運行的替換驗證腳本，Cloud Build 失敗並出現錯誤 SUBSTITUTIONVARIABLENOT_DEFINED

已發表: 2025-11-29

Cloud Build 已成為許多開發人員和組織持續集成和部署工作流程中的關鍵工具。它與其他 Google Cloud Platform (GCP) 產品和可編寫腳本的工作流程緊密集成，使其成為需要可定制和可擴展的 CI/CD 管道的團隊的最愛。然而，與許多強大的工具一樣，Cloud Build 也有其怪癖，尤其是在變量和參數化方面。最近許多開發人員遇到的一個令人沮喪的問題是SUBSTITUTION_VARIABLE_NOT_DEFINED錯誤。這個難以捉摸的問題可能會導致整個管道停止運行，影響開發速度並增加故障排除時間。

長話短說

如果您的 Cloud Build 管道失敗並出現SUBSTITUTION_VARIABLE_NOT_DEFINED錯誤，則可能意味著您的構建觸發器或配置文件中缺少所需的替換變量。當使用跨存儲庫共享的 CI 模板時，這種情況很常見。自定義變量驗證腳本通過在運行時檢查所有必需的變量來修復此問題，提供更清晰的反饋並防止錯誤的構建。該解決方法還提高了整體管道的穩健性並最大限度地減少了手動調試工作。

了解 SUBSTITUTION_VARIABLE_NOT_DEFINED 錯誤

當構建流程引用尚未在該構建上下文中定義的替換變量時，Cloud Build 會發出SUBSTITUTION_VARIABLE_NOT_DEFINED錯誤。這些替換變量允許您自定義構建步驟和模板，而無需將值直接硬編碼到管道 YAML 中，從而提高可重用性和清晰度。

例如，常見的 Cloud Build 模板可能包括如下所示的構建步驟：

步驟：
- 名稱：'gcr.io/cloud-builders/docker'
  參數：['build', '-t', '${_IMAGE_NAME}', '.']

這裡， ${_IMAGE_NAME}是用戶定義的替換變量。如果在觸發構建時未提供此變量（可能通過觸發器配置或命令行），Cloud Build 將立即失敗並出現SUBSTITUTION_VARIABLE_NOT_DEFINED錯誤。

CI 模板實現的根本原因

當團隊使用共享模板時，或者當不同的存儲庫通過集中式 YAML 配置搭載相同的 CI 邏輯時，這個問題變得特別麻煩。通常，每個存儲庫或構建觸發器可能需要定義不同的變量，但強制一致性變得具有挑戰性。許多團隊假設替換變量是可選的，或者它有默認的後備，只有當該變量在需要它的構建上下文中不存在時才會遇到此錯誤。

可能出現此錯誤的情況：

當觸發器設置中忘記默認值時
添加新模板但未記錄或強制執行所有必需的變量時
當開發人員跨環境（例如，登台、生產）克隆模板但省略特定變量定義時

實用的修復：替換驗證腳本

為了解決這個問題並防止未來的中斷，幾個團隊引入了預驗證機制 - 一個嵌入式驗證腳本，該腳本在管道開始時運行，以在執行任何關鍵步驟之前檢查所需的替換變量。

該腳本掃描當前環境並嘗試斷言所有關鍵變量是否存在（有時是類型或模式）。如果缺少任何變量，它會提前停止執行並提供一個人類可讀的缺少變量的列表。

下面是用 bash 編寫的此類腳本的簡化示例：

#!/bin/bash
設置-e

REQUIRED_VARS=(
  “_IMAGE_NAME”
  “_SERVICE_NAME”
）

對於“${REQUIRED_VARS[@]}”中的 VAR
做
  如果 [[ -z "${!VAR}" ]];然後
    echo“錯誤：未定義所需的替換變量 ${VAR}。”
    1號出口
  菲
完畢

echo“所有必需的替換變量都存在。”

通過將此步驟放在構建管道的頂部，團隊可以及早發現錯誤，減少浪費的計算週期，並向其他開發人員提供更有用的反饋。

集成到雲構建工作流程中

在實際工作流程中，驗證 shell 腳本可以作為內聯命令包含在內，也可以從安全位置（例如版本控制的 GCS 存儲桶）中的共享腳本文件導入。這通常是 cloudbuild.yaml 文件中的第一步：

步驟：
- 名稱：'gcr.io/cloud-builders/bash'
  入口點：'bash'
  參數：['-c', './validate_vars.sh']

這使團隊能夠：

版本化他們的 CI 驗證邏輯
維護預期變量的單一事實來源
減少涉及試錯觸發器編輯的嘈雜調試週期

增強的開發人員體驗

該驗證腳本的引入產生了立竿見影的效果：

由於未被注意到的缺失變量而導致的管道故障更少。
更清晰的錯誤消息直接指向問題，而不是晦澀的日誌。
新開發人員可以更快地入職，他們可以重用現有的 CI 工作流程，而無需了解預期變量的完整知識。

隨著時間的推移，一些團隊擴展了驗證器以允許可選變量並設置後備，從而為共享模板提供了更大的靈活性。其他人將其與 YAML 模式驗證配對，以在運行時檢查整個 cloudbuild.yaml 管道。

防止新項目中的錯誤

為了使未來的項目免受此問題的影響，建議遵循以下最佳實踐：

在存儲庫的 README 或 CI 指南中記錄所有必需的替換變量。
在添加到 CI/CD 工作流程的每個新模板中使用驗證腳本。
定義清晰的命名約定（例如，以 _ 開頭的變量意味著需要自定義替換）。
在適當的情況下在構建中設置默認值或通過腳本提供可選的變量邏輯。

最後的想法

儘管SUBSTITUTION_VARIABLE_NOT_DEFINED錯誤乍一看似乎無害，但它代表了 CI/CD 衛生和配置管理中更廣泛的問題。將變量驗證視為管道的一流組件可確保更強大的自動化實踐、更少的損壞構建以及更快樂的開發人員。通過引入簡單的驗證腳本，許多團隊能夠簡化其管道工作流程並顯著減少停機時間和調試工作。

常見問題解答：雲構建替換變量和驗證

問：Cloud Build 中的替代變量是什麼？
替換變量是 cloudbuild.yaml 文件中的佔位符，觸發構建時將替換為實際值。這些變量用於為不同的環境或配置定制構建。
問：為什麼我會看到 SUBSTITUTION_VARIABLE_NOT_DEFINED 錯誤？
當 YAML 文件中引用的變量未通過構建觸發器或環境傳遞，導致其在運行時未定義時，通常會發生此錯誤。
問：觸發構建時如何提供替換變量？
您可以在設置觸發器時通過 Google Cloud Console 傳遞替換變量，或者使用--substitutions標誌通過 gcloud CLI 傳遞替換變量。
問：我可以為替換變量設置默認值嗎？
Cloud Build 不支持直接在 YAML 中使用默認值，但您可以編寫邏輯腳本來處理未定義的變量，並在 bash 或 Python 腳本中以編程方式分配後備值。
問：在多個項目中強制變量存在的最佳方法是什麼？
在所有 cloudbuild.yaml 模板的開頭使用共享驗證腳本來強制一致性並在繼續構建作業之前驗證輸入。