Cloud Build nie działa z powodu błędu SUBSTITUTIONVARIABLENOT_DEFINED dla szablonów CI i skryptu sprawdzającego podstawienie uruchamianego naprawionego potoku

Opublikowany: 2025-11-29

Cloud Build stał się kluczowym narzędziem w procesach ciągłej integracji i wdrażania wielu programistów i organizacji. Ścisła integracja z innymi produktami Google Cloud Platform (GCP) i skryptowalnymi przepływami pracy sprawia, że jest to ulubione rozwiązanie dla zespołów poszukujących konfigurowalnych i skalowalnych potoków CI/CD. Jednakże, podobnie jak w przypadku wielu potężnych narzędzi, Cloud Build nie jest pozbawiony dziwactw — szczególnie jeśli chodzi o zmienne i parametryzację. Frustrującym problemem, którego ostatnio doświadcza wielu programistów, jest błądSUBSTITUTION_VARIABLE_NOT_DEFINED. Ten nieuchwytny problem może zatrzymać cały potok, wpływając na prędkość programowania i wydłużając czas rozwiązywania problemów.

TL;DR

Jeśli potok Cloud Build nie działa z powodu błęduSUBSTITUTION_VARIABLE_NOT_DEFINED, prawdopodobnie oznacza to, że w aktywatorze kompilacji lub pliku konfiguracyjnym brakuje wymaganej zmiennej zastępczej. Jest to częste zjawisko w przypadku korzystania z szablonów CI współdzielonych w repozytoriach. Niestandardowy skrypt sprawdzania poprawności zmiennych rozwiązał ten problem, sprawdzając wszystkie wymagane zmienne w czasie wykonywania, zapewniając wyraźniejsze informacje zwrotne i zapobiegając błędnym kompilacjom. To obejście poprawiło również ogólną niezawodność potoku i zminimalizowało wysiłki związane z ręcznym debugowaniem.

Zrozumienie błędu SUBSTITUTION_VARIABLE_NOT_DEFINED

BłądSUBSTITUTION_VARIABLE_NOT_DEFINEDjest emitowany przez Cloud Build, gdy proces kompilacji odwołuje się do zmiennej zastępczej, która nie została zdefiniowana w kontekście tej kompilacji. Te zmienne zastępcze umożliwiają dostosowywanie etapów kompilacji i szablonów bez konieczności kodowania wartości bezpośrednio w potoku YAML, co poprawia możliwość ponownego użycia i przejrzystość.

Na przykład typowy szablon Cloud Build może zawierać następujące kroki kompilacji:

kroki:
- nazwa: 'gcr.io/cloud-builders/docker'
  argumenty: ['kompilacja', '-t', '${_IMAGE_NAME}', '.']

Tutaj ${_IMAGE_NAME} jest zmienną zastępczą zdefiniowaną przez użytkownika. Jeśli ta zmienna nie zostanie podana w momencie uruchomienia kompilacji, na przykład poprzez konfigurację wyzwalacza lub wiersz poleceń, Cloud Build natychmiast zakończy się niepowodzeniem i wystąpi błądSUBSTITUTION_VARIABLE_NOT_DEFINED.

Podstawowe przyczyny implementacji szablonów CI

Ten problem staje się szczególnie kłopotliwy, gdy zespoły korzystają ze wspólnych szablonów lub gdy różne repozytoria wykorzystują tę samą logikę CI za pośrednictwem scentralizowanych konfiguracji YAML. Często każde repozytorium lub wyzwalacz kompilacji może wymagać zdefiniowania różnych zmiennych, ale egzekwowanie spójności staje się wyzwaniem. Wiele zespołów zakłada, że zmienna zastępcza jest opcjonalna lub ma domyślną rezerwę, ale napotyka ten błąd, gdy zmienna jest nieobecna w kontekście kompilacji, który jej oczekuje.

Sytuacje, w których może pojawić się ten błąd:

Gdy w ustawieniach wyzwalacza zostanie zapomniana wartość domyślna
Gdy dodano nowy szablon, ale nie wszystkie wymagane zmienne są udokumentowane lub wymuszone
Kiedy programiści klonują szablony w różnych środowiskach (np. Staging, Production), ale pomijają określone definicje zmiennych

Pragmatyczna poprawka: skrypt sprawdzający poprawność podstawienia

Aby rozwiązać ten problem i zapobiec przyszłym zakłóceniom, kilka zespołów wprowadziło mechanizm wstępnej walidacji — osadzonyskrypt sprawdzający, który jest uruchamiany na początku potoku w celu sprawdzenia wymaganych zmiennych zastępczych przed wykonaniem jakichkolwiek krytycznych kroków.

Skrypt skanuje bieżące środowisko i próbuje potwierdzić obecność (a czasem typ lub wzorzec) wszystkich krytycznych zmiennych. Jeżeli któregokolwiek brakuje, zatrzymuje wykonywanie wcześniej i udostępnia czytelną dla człowieka listę brakujących zmiennych.

Oto uproszczony przykład takiego skryptu napisanego w bashu:

#!/bin/bash
zestaw -e

WYMAGANE_WARUNKI=(
  „_IMAGE_NAME”
  „_NAZWA_USŁUGI”
)

dla VAR w „${REQUIRED_VARS[@]}”
Do
  jeśli [[ -z "${!VAR}" ]]; Następnie
    echo "BŁĄD: Nie zdefiniowano wymaganej zmiennej zastępczej ${VAR}."
    wyjście 1
  fi
zrobione

echo "Występują wszystkie wymagane zmienne zastępcze."

Umieszczając ten krok na początku potoku kompilacji, zespoły mogą wcześnie wychwytywać błędy, ograniczać niepotrzebne cykle obliczeniowe i przekazywać bardziej pomocne opinie innym programistom.

Integracja z przepływami pracy Cloud Build

W praktycznych przepływach pracy skrypt powłoki sprawdzającej można dołączyć jako polecenie wbudowane lub zaimportować z udostępnionego pliku skryptu w bezpiecznej lokalizacji, np. wersjonowanego zasobnika GCS. Zwykle jest to pierwszy krok w pliku cloudbuild.yaml:

kroki:
- nazwa: 'gcr.io/cloud-builders/bash'
  punkt wejścia: „bash”
  argumenty: ['-c', './validate_vars.sh']

Daje to zespołom możliwość:

Wersjonuj logikę sprawdzania poprawności CI
Utrzymuj jedno źródło prawdy dla oczekiwanych zmiennych
Ogranicz hałaśliwe cykle debugowania poprzez edycję wyzwalacza metodą prób i błędów

Ulepszone doświadczenie programisty

Wprowadzenie tego skryptu walidacyjnego miało natychmiastowe skutki:

Mniej awarii rurociągówz powodu niezauważonych brakujących zmiennych.
Wyraźniejsze komunikaty o błędach, które wskazywały bezpośrednio na problem, zamiast niejasnych dzienników.
Szybsze wdrażanienowych programistów, którzy ponownie wykorzystali istniejące przepływy pracy CI bez konieczności posiadania pełnej wiedzy plemiennej na temat oczekiwanych zmiennych.

Z biegiem czasu niektóre zespoły rozszerzyły walidator, aby umożliwićopcjonalnezmienne i ustawić rezerwy, zapewniając jeszcze większą elastyczność udostępnianym szablonom. Inni połączyli to z walidacją schematu YAML, aby w czasie wykonywania uruchomić cały potok cloudbuild.yaml.

Zapobieganie błędom w nowych projektach

Aby przyszłe projekty były wolne od tego problemu, zaleca się przestrzeganie następujących najlepszych praktyk:

Udokumentuj wszystkie wymagane zmienne zastępczew przewodniku README lub CI dla repozytorium.
Użyj skryptu walidacyjnegow każdym nowym szablonie dodawanym do przepływów pracy CI/CD.
Zdefiniuj jasne konwencje nazewnictwa(np. zmienne zaczynające się od _ oznaczają wymagane niestandardowe podstawienia).
W stosownych przypadkachustaw wartości domyślnew kompilacjach lub zapewnij opcjonalną logikę zmiennych za pomocą skryptów.

Ostatnie przemyślenia

Chociaż błądSUBSTITUTION_VARIABLE_NOT_DEFINEDmoże na pierwszy rzut oka wydawać się nieszkodliwy, stanowi on szerszy problem w zarządzaniu higieną CI/CD i konfiguracją. Traktowanie sprawdzania poprawności zmiennych jako pierwszorzędnego komponentu potoku zapewnia lepsze praktyki automatyzacji, mniej uszkodzonych kompilacji i szczęśliwszych programistów. Wprowadzając prosty skrypt sprawdzający, wiele zespołów było w stanie usprawnić przepływy pracy i znacząco ograniczyć przestoje i wysiłek związany z debugowaniem.

Często zadawane pytania: zmienne zastępcze i weryfikacja Cloud Build

P: Co to jest zmienna zastępcza w Cloud Build?
Zmienna zastępcza to element zastępczy w pliku cloudbuild.yaml, który jest zastępowany rzeczywistymi wartościami po uruchomieniu kompilacji. Zmienne te służą do dostosowywania kompilacji do różnych środowisk lub konfiguracji.
P: Dlaczego widzę błędy SUBSTITUTION_VARIABLE_NOT_DEFINED?
Ten błąd zwykle występuje, gdy zmienna, do której odwołuje się plik YAML, nie jest przekazywana przez wyzwalacz kompilacji lub środowisko, przez co jest niezdefiniowana w czasie wykonywania.
P: Jak mogę podać zmienne zastępcze podczas uruchamiania kompilacji?
Zmienne podstawieniowe możesz przekazywać za pomocą konsoli Google Cloud podczas konfigurowania aktywatora lub za pomocą interfejsu wiersza polecenia gcloud, używając flagi --substitutions .
P: Czy mogę ustawić wartości domyślne zmiennych podstawieniowych?
Cloud Build nie obsługuje wartości domyślnych bezpośrednio w YAML, ale możesz stworzyć logikę skryptową, która obsłuży niezdefiniowane zmienne i programowo przypisz wartości rezerwowe w skryptach bash lub Python.
P: Jaki jest najlepszy sposób wymuszenia obecności zmiennej w wielu projektach?
Użyj udostępnionego skryptu sprawdzania poprawności na początku wszystkich szablonów cloudbuild.yaml, aby wymusić spójność i sprawdzić poprawność danych wejściowych przed kontynuowaniem zadania kompilacji.