Alibaba Cloud DevOps：環境變數

內建變數使用限制

使用內建變數時，注意以下限制和特殊情境：

• 多代碼源變數歧義風險：當流水線配置了多個代碼源時，不要直接使用無下標的 CI_COMMIT_REF_NAME、CI_COMMIT_SHA 等變數。雖然系統預設取第一個代碼源的值，但結果不可預期。應始終使用帶數字尾碼的變數（如 CI_COMMIT_REF_NAME_1、CI_COMMIT_REF_NAME_2）明確指定代碼源。

• Git 變數擷取前提：CI_COMMIT_TITLE、CI_COMMIT_SHA、CI_COMMIT_ID 等 Git 相關內建變數，必須在流水線中添加"擷取代碼"步驟後才能擷取到值。若流水線未配置代碼拉取步驟，這些變數將為空白。

• 變數處理限制：雲效流水線不支援對系統內建變數（如 CI_COMMIT_ID）直接進行字串截取、正則提取等函數處理。如需對變數值進行加工，在 Shell 指令碼中先將其賦值給自訂變數，再對自訂變數進行操作。樣本如下：

  # 將內建變數賦值給自訂變數後再處理
  MY_SHORT_ID=$(echo $CI_COMMIT_ID | cut -c1-8)
  echo "MY_SHORT_ID=$MY_SHORT_ID" >> "$FLOW_ENV"

• CI_WORKSPACE 適用範圍：CI_WORKSPACE 僅在當前構建環境有效。在主機部署（ECS）情境中，該變數可能無效或指向非預期路徑，不要依賴此變數定位 ECS 上的檔案。

• 缺失變數說明：內建變數不包含"當前倉庫專案名"或"完整 Git 地址"。如需這些資訊，可通過自訂變數手動設定，或結合 Codeup 網域名稱自行拼接 Git 倉庫地址。

字元變數

1. 在流水線變數和緩衝 > 字元變數處，單擊 建立變數，開啟建立變數彈窗。

2. 輸入變數名稱和預設值，可以設定私密模式和運行時設定。

   1. 變數名稱：注意環境變數名稱不可使用橫杠符號 - 。

   2. 私密模式：控制變數是否對外公開。當變數設定為私密模式後，將無法查看變數的值，相應的執行日誌中也不會顯示。通常適用於使用者名稱，密碼等私密資訊情境。

   3. 運行時設定：控制變數值是否需要在流水線運行時設定。當變數設定為運行時設定後，流水線運行時需要設定變數的值。通常適用於需要動態配置流水線參數值情境。

3. 可以添加更多變數，也可以刪除變數。

4. 單擊添加後，需要儲存流水線才可以將變數儲存至流水線。儲存完畢後即可按情境 使用環境變數。

運行選擇變數

1. 在流水線變數和緩衝 > 運行選擇變數處，單擊 建立變數，開啟建立變數彈窗。

2. 輸入變數名稱和選項。

   1. 單擊添加選項可以為變數取值添加多個選項。

   2. 選項開啟預設值則該選項為該變數的預設取值。

3. 單擊添加後，需要儲存流水線才可以將變數儲存至流水線。儲存完畢後即可按情境 使用環境變數。

4. 在流水線點擊運行時需要選擇變數取值。

自訂變數最佳實務

• 命名衝突規避：自訂變數名應避免與系統預置變數名或常見構建參數衝突。例如，image、tag 等變數名可能與鏡像構建步驟的內建參數衝突，導致構建步驟報錯或行為異常。建議為自訂變數添加業務首碼（如 APP_IMAGE、DEPLOY_TAG）以避免衝突。變數命名規則：以字母開頭，僅支援大小寫字母、數字和底線（_），長度 1~64 個字元，且不允許與預置變數名重複。

• 特殊字元轉義：當變數值包含 @、#、& 等特殊字元時（如使用者名稱或密碼），直接在 URL 中拼接會導致格式錯誤。例如，密碼 pass@123 在 URL https://user:pass@123@host 中會被錯誤解析。建議採用以下方案之一：

  • 對特殊字元進行 URL 編碼（如 @ 轉為 %40），將 pass@123 編碼為 pass%40123。

  • 使用憑據管理或將變數設為私密模式，由系統自動處理認證資訊，避免手動拼接。

• 動態代碼源許可權：流水線不支援自動以執行者身份登入動態代碼倉庫。如需在流水線中訪問非預配置的代碼倉庫，建議將 Git 帳號和個人存取權杖（Token）配置為私密變數，在指令碼中通過變數引用完成認證；或使用流水線代碼源配置方式擷取代碼許可權。

• YAML 變數轉義：在 kubectl apply 等情境中，YAML 檔案中的 ${} 文法會被流水線引擎誤識別為流水線變數並進行替換。解決方案：

  • 在流水線步驟配置中勾選變數校正選項，禁用自動變數解析。

  • 使用轉義文法 $${變數名} 保留原始字串。例如，YAML 中需要保留 ${2} 時，在流水線配置中寫為 $${2}。