Cloud Build eșuează cu eroarea SUBSTITUTIONVARIABLENOT_DEFINED pentru șabloanele CI și scriptul de validare a înlocuirii care rulează pipeline fix

Publicat: 2025-11-29

Cloud Build a devenit un instrument esențial în fluxurile de lucru continue de integrare și implementare ale multor dezvoltatori și organizații. Integrarea sa strânsă cu alte produse Google Cloud Platform (GCP) și fluxuri de lucru cu scripturi îl fac favorit pentru echipele care doresc conducte CI/CD personalizabile și scalabile. Cu toate acestea, ca și în cazul multor instrumente puternice, Cloud Build nu este lipsit de ciudateniile sale, mai ales când vine vorba de variabile și parametrizare. O problemă frustrantă întâlnită recent de mulți dezvoltatori este eroareaSUBSTITUTION_VARIABLE_NOT_DEFINED. Această problemă evazivă poate opri o întreagă conductă, afectând viteza de dezvoltare și crescând timpul de depanare.

TL;DR

Dacă canalul dvs. Cloud Build eșuează cu o eroareSUBSTITUTION_VARIABLE_NOT_DEFINED, înseamnă probabil că lipsește o variabilă de înlocuire necesară din declanșatorul de compilare sau din fișierul de configurare. Acest lucru este obișnuit atunci când se utilizează șabloane CI partajate între depozite. Un script personalizat de validare a variabilelor a remediat acest lucru prin verificarea tuturor variabilelor necesare în timpul execuției, oferind feedback mai clar și prevenind versiunile defectuoase. Soluția a îmbunătățit, de asemenea, robustețea generală a conductei și a minimizat eforturile de depanare manuală.

Înțelegerea erorii SUBSTITUTION_VARIABLE_NOT_DEFINED

EroareaSUBSTITUTION_VARIABLE_NOT_DEFINEDeste emisă de Cloud Build atunci când un proces de compilare face referire la o variabilă de substituție care nu a fost definită în contextul acelei versiuni. Aceste variabile de înlocuire vă permit să personalizați pașii de construcție și șabloanele fără a codifica valori direct în conducta YAML, îmbunătățind reutilizarea și claritatea.

De exemplu, un șablon Cloud Build obișnuit poate include pași de construcție precum următorii:

pași:
- nume: „gcr.io/cloud-builders/docker”
  args: ['build', '-t', '${_IMAGE_NAME}', '.']

Aici, ${_IMAGE_NAME} este o variabilă de substituție definită de utilizator. Dacă această variabilă nu este furnizată în momentul în care este declanșată construcția, poate printr-o configurație de declanșare sau printr-o linie de comandă, Cloud Build va eșua imediat cu o eroareSUBSTITUTION_VARIABLE_NOT_DEFINED.

Cauzele fundamentale în implementările de șabloane CI

Această problemă devine deosebit de deranjantă atunci când echipele folosesc șabloane partajate sau atunci când diferite depozite aduc aceeași logică CI prin configurații YAML centralizate. Adesea, fiecare depozit sau declanșator de compilare ar putea avea nevoie să definească diferite variabile, dar impunerea coerenței devine o provocare. Multe echipe presupun că o variabilă de înlocuire este opțională sau că are o alternativă implicită, doar pentru a întâmpina această eroare atunci când variabila este absentă într-un context de construcție care o așteaptă.

Situații în care este probabil să apară această eroare:

Când o valoare implicită este uitată în setările de declanșare
Când se adaugă un șablon nou, dar nu toate variabilele necesare sunt documentate sau aplicate
Când dezvoltatorii clonează șabloane în diferite medii (de exemplu, punere în scenă, producție), dar omit definiții de variabile specifice

O remediere pragmatică: Scriptul de validare a înlocuirii

Pentru a rezolva această problemă și a preveni întreruperile viitoare, mai multe echipe au introdus un mecanism de prevalidare - unscript de validareîncorporat care rulează la începutul conductei pentru a verifica variabilele de înlocuire necesare înainte de executarea oricăror pași critici.

Scriptul scanează mediul curent și încearcă să afirme prezența (și uneori tipul sau modelul) tuturor variabilelor critice. Dacă lipsesc vreuna, se oprește execuția devreme și oferă o listă care poate fi citită de om a variabilelor care au lipsit.

Iată un exemplu simplificat al unui astfel de script scris în bash:

#!/bin/bash
set -e

REQUIRED_VARS=(
  „_IMAGE_NAME”
  „_SERVICE_NAME”
)

pentru VAR în „${REQUIRED_VARS[@]}”
do
  dacă [[ -z "${!VAR}" ]]; apoi
    echo "EROARE: variabila de substituție necesară ${VAR} nu este definită."
    iesirea 1
  fi
făcut

echo "Toate variabilele de substituție necesare sunt prezente."

Plasând acest pas în vârful canalului de construire, echipele pot detecta erorile din timp, pot reduce ciclurile de calcul irosite și pot oferi feedback mai util altor dezvoltatori.

Integrare în fluxurile de lucru Cloud Build

În fluxurile de lucru practice, scriptul shell de validare poate fi inclus fie ca o comandă inline, fie importat dintr-un fișier de script partajat într-o locație sigură, cum ar fi un bucket GCS cu versiune. Este de obicei primul pas în fișierul cloudbuild.yaml:

pași:
- nume: „gcr.io/cloud-builders/bash”
  punct de intrare: „bash”
  argumente: ['-c', './validate_vars.sh']

Acest lucru oferă echipelor capacitatea de a:

Versiune logica lor de validare CI
Mențineți o singură sursă de adevăr pentru variabilele așteptate
Reduceți ciclurile de depanare zgomotoase care implică editarea declanșatorului prin încercare și eroare

Experiență îmbunătățită a dezvoltatorului

Introducerea acestui script de validare a avut efecte imediate:

Mai puține defecțiuni ale conducteidin cauza variabilelor lipsă neobservate.
Mesaje de eroare mai clarecare au indicat direct problema în loc de jurnalele obscure.
Integrare mai rapidăa noilor dezvoltatori care au reutilizat fluxurile de lucru CI existente fără a avea nevoie de cunoștințe tribale complete despre variabilele așteptate.

De-a lungul timpului, unele echipe au extins validatorul pentru a permite variabileopționaleși pentru a seta alternative, oferind și mai multă flexibilitate șabloanelor partajate. Alții l-au împerecheat cu validarea schemei YAML pentru a-și strică întreaga conductă cloudbuild.yaml în timpul execuției.

Prevenirea erorilor în proiecte noi

Pentru a menține proiectele viitoare libere de această problemă, se recomandă să urmați aceste bune practici:

Documentați toate variabilele de înlocuire necesareîn ghidul README sau CI pentru repo.
Utilizați un script de validareîn fiecare șablon nou adăugat fluxurilor de lucru CI/CD.
Definiți convenții clare de denumire(de exemplu, variabilele care încep cu _ implică înlocuiri personalizate necesare).
Setați valorile impliciteîn versiuni acolo unde este cazul sau furnizați o logică variabilă opțională prin scripting.

Gânduri finale

Deși eroareaSUBSTITUTION_VARIABLE_NOT_DEFINEDpoate părea inofensivă la prima vedere, reprezintă o problemă mai amplă în igiena CI/CD și gestionarea configurației. Tratarea validării variabilelor ca pe o componentă de primă clasă a conductei dvs. asigură practici de automatizare mai puternice, mai puține versiuni întrerupte și dezvoltatori mai fericiți. Prin introducerea unui script de validare simplu, multe echipe au reușit să-și eficientizeze fluxurile de lucru ale conductei și să reducă semnificativ timpul de nefuncționare și efortul de depanare.

Întrebări frecvente: Variabile și validare de înlocuire a Cloud Build

Î: Ce este o variabilă de substituție în Cloud Build?
O variabilă de substituție este un substituent din fișierul dvs. cloudbuild.yaml care este înlocuit cu valori reale atunci când construirea este declanșată. Aceste variabile sunt folosite pentru a personaliza versiunile pentru diferite medii sau configurații.
Î: De ce văd erori SUBSTITUTION_VARIABLE_NOT_DEFINED?
Această eroare apare de obicei atunci când o variabilă la care se face referire în fișierul YAML nu este trecută prin declanșatorul de compilare sau prin mediu, ceea ce o face nedefinită în timpul execuției.
Î: Cum pot furniza variabile de înlocuire când declanșez o construcție?
Puteți trece variabile de înlocuire prin Google Cloud Console atunci când configurați declanșatorul sau prin intermediul CLI gcloud utilizând indicatorul --substitutions .
Î: Pot seta valori implicite pentru variabilele de substituție?
Cloud Build nu acceptă valorile implicite direct în YAML, dar puteți crea scripturi logice pentru a gestiona variabile nedefinite și a atribui fallback-uri în mod programatic în scripturile bash sau Python.
Î: Care este cea mai bună modalitate de a impune prezența variabilă în mai multe proiecte?
Utilizați un script de validare partajat la începutul tuturor șabloanelor cloudbuild.yaml pentru a impune coerența și a valida intrările înainte de a continua cu munca de compilare.