Fehlerbehebung bei Bash-Variablenexpansion effektiv

Bash-Variablenexpansionsfehler sehen oft wie zufälliges Verhalten aus: Ein Pfad mit Leerzeichen wird zu zwei Pfaden, ein Platzhalter in einem Dateinamen expandiert zu einem halben Verzeichnis, eine in einer Schleife gesetzte Variable verschwindet oder eine fehlende Umgebungsvariable wird stillschweigend zu einer leeren Zeichenfolge. Die Shell ist nicht zufällig. Sie folgt Expansionsregeln, die leicht zu vergessen sind, wenn man sich auf die Aufgabe konzentriert, die das Skript erledigen soll.

Das nützliche mentale Modell ist dies: Bash ersetzt nicht einfach $name durch Text und führt den Befehl aus. Es expandiert Variablen, kann das Ergebnis in Wörter aufteilen, kann Globs expandieren und führt dann schließlich einen Befehl mit der resultierenden Argumentliste aus. Die meisten Korrekturen ergeben sich aus der Kontrolle dieser Schritte.

Nicht gesetzte Variablen werden leer, es sei denn, Sie verhindern dies

Standardmäßig gibt dieses Skript einen leeren Wert aus und fährt fort:

printf 'Deploying %s\n' "$APP_VERSION"

Wenn APP_VERSION erforderlich war, ist das ein Fehler. Verwenden Sie die Parameterexpansion, wenn die Variable obligatorisch ist:

: "${APP_VERSION:?APP_VERSION muss gesetzt sein}"
printf 'Deploying %s\n' "$APP_VERSION"

Das führende : ist der No-Op-Befehl. Die Expansion führt die Überprüfung durch. Wenn die Variable nicht gesetzt oder leer ist, gibt Bash die Meldung aus und beendet sich in einer nicht-interaktiven Shell.

Für optionale Werte machen Sie den Standardwert offensichtlich:

log_level=${LOG_LEVEL:-INFO}
retry_count=${RETRY_COUNT:-3}

Der Doppelpunkt ist wichtig. ${VAR:-default} verwendet den Standardwert, wenn VAR nicht gesetzt oder leer ist. ${VAR-default} verwendet den Standardwert nur, wenn VAR nicht gesetzt ist. Diese Unterscheidung ist wichtig, wenn eine leere Zeichenfolge ein gültiger Konfigurationswert ist.

set -u kann auch nicht gesetzte Variablen abfangen:

set -u

Es ist in vielen Skripten nützlich, aber es ist kein Ersatz für eine klare Validierung. Es kann Sie auch überraschen, wenn Sie mit optionalen Positionsparametern, Arrays oder Variablen arbeiten, die absichtlich auf Existenz überprüft werden. Verwenden Sie ${1:-}, wenn ein Argument fehlen könnte:

mode=${1:-help}

Setzen Sie Variablen in Anführungszeichen, es sei denn, Sie möchten Aufteilung und Globbing

Dies ist das häufigste Expansionsproblem:

file="Quarterly Report *.txt"
rm $file

Ohne Anführungszeichen expandiert Bash zuerst $file, teilt es dann an Leerzeichen auf und behandelt dann * als Platzhalter. Der Befehl erhält möglicherweise mehrere Argumente, die Sie nicht beabsichtigt haben. In Anführungszeichen erhält er genau ein Argument:

rm -- "$file"

Das -- schützt Befehle vor Werten, die mit einem Bindestrich beginnen. Das ist wichtig für Dateinamen wie -rf.

Verwenden Sie doppelte Anführungszeichen für Variablen, Befehlsersetzungen und die meisten Parameterexpansionen:

cp "$source_file" "$destination_dir/"
printf 'User: %s\n' "$user_name"

Einfache Anführungszeichen sind anders. Sie verhindern die Expansion vollständig:

printf 'Home is $HOME\n'   # gibt den Literaltext aus
printf "Home is $HOME\n"   # gibt den Wert aus

Wenn Sie ein Skript sehen, das Zeichenfolgen wie 'prefix-$value' erstellt, ist das wahrscheinlich ein Fehler. Verwenden Sie doppelte Anführungszeichen, wenn der Wert expandiert werden soll.

Arrays lösen viele Probleme beim Erstellen von Argumentlisten

Viele kaputte Bash-Skripte entstehen dadurch, dass mehrere Befehlsoptionen in einer Zeichenfolge gespeichert werden:

opts="-a --delete --exclude *.tmp"
rsync $opts "$src/" "$dest/"

Das verlässt sich auf die Wortaufteilung und kann brechen, wenn ein Optionsargument Leerzeichen enthält. Verwenden Sie ein Array:

opts=(-a --delete --exclude '*.tmp')
rsync "${opts[@]}" "$src/" "$dest/"

"${opts[@]}" expandiert jedes Array-Element als eigenes Argument. Das ist genau das, was die meisten Befehlskonstruktionen benötigen.

Das Gleiche gilt beim Sammeln von Dateinamen:

files=("$report_dir"/*.txt)
for file in "${files[@]}"; do
  [[ -e $file ]] || continue
  process_report "$file"
done

Die [[ -e $file ]] || continue-Absicherung behandelt den Fall, dass keine Dateien übereinstimmen und der Glob literal bleibt, abhängig von den Shell-Optionen.

Befehlsersetzung entfernt nachfolgende Zeilenumbrüche

$(command) erfasst stdout, aber Bash entfernt nachfolgende Zeilenumbruchzeichen. Das ist normalerweise in Ordnung für eine Versionszeichenfolge und falsch für Daten, bei denen abschließende Zeilenumbrüche wichtig sind.

version=$(git describe --tags --always)
printf 'Version: %s\n' "$version"

Für zeilenorientierte Ausgaben bevorzugen Sie mapfile, wenn Sie ein Array benötigen:

mapfile -t names < <(find "$base_dir" -maxdepth 1 -type f -name '*.log' -printf '%f\n')
for name in "${names[@]}"; do
  printf 'log=%s\n' "$name"
done

Vermeiden Sie for item in $(ls). Es bricht bei Leerzeichen, Glob-Zeichen und ungewöhnlichen Dateinamen. Schleifen Sie über Globs oder verwenden Sie find mit sorgfältigen Trennzeichen.

Variablen in Pipelines können sich in einer Subshell befinden

Das fängt Leute, weil die Schleife korrekt zu laufen scheint:

count=0
printf '%s\n' a b c | while IFS= read -r line; do
  count=$((count + 1))
done
printf 'count=%s\n' "$count"

In vielen Bash-Konfigurationen läuft die while-Schleife in einer Pipeline in einer Subshell. Die Erhöhung findet statt, aber die count-Variable der übergeordneten Shell bleibt unverändert.

Verwenden Sie stattdessen die Prozesssubstitution:

count=0
while IFS= read -r line; do
  count=$((count + 1))
done < <(printf '%s\n' a b c)
printf 'count=%s\n' "$count"

Oder lassen Sie die Pipeline den Wert produzieren, den Sie benötigen, und erfassen Sie diesen Wert direkt.

Lokale Variablen verhindern versehentliche Überschreibungen

Variablen in Bash-Funktionen sind global, es sei denn, sie werden als local deklariert. Dies kann eine Hilfsfunktion zu einer Quelle seltsamer Expansionsfehler machen:

env=prod

load_config() {
  env=dev
}

load_config
printf '%s\n' "$env"  # dev

Verwenden Sie local für temporäre Werte:

load_config() {
  local env=dev
  printf 'loaded defaults for %s\n' "$env"
}

local ist eine Bash-Funktion. Das ist in Bash-Skripten in Ordnung, aber es ist ein weiterer Grund, warum das Skript nicht mit sh ausgeführt werden sollte.

Verwenden Sie geschweifte Klammern, wenn Namen anderen Text berühren

$prefix_file bedeutet eine Variable namens prefix_file, nicht $prefix gefolgt von _file. Verwenden Sie geschweifte Klammern, um die Grenze klar zu machen:

prefix=app
printf '%s\n' "${prefix}_file"

Geschweifte Klammern sind auch für viele Parameterexpansionsoperationen erforderlich:

path=/var/log/nginx/access.log
printf 'dir=%s\n' "${path%/*}"
printf 'file=%s\n' "${path##*/}"

${path%/*} entfernt das kürzeste passende Suffix. ${path##*/} entfernt das längste passende Präfix. Diese sind nützlich, aber überbeanspruchen Sie sie nicht, wenn dirname oder basename das Skript für Ihr Team klarer machen würden.

Debuggen Sie die Expansion, indem Sie die tatsächlichen Argumente ausgeben

set -x zeigt Befehle nach der Expansion an. Verbessern Sie die Ablaufverfolgung mit Zeilennummern:

PS4='+ ${BASH_SOURCE}:${LINENO}: '
set -x
mv $file $target_dir
set +x

Die Ablaufverfolgung zeigt, ob der Befehl zu mv Quarterly Report *.txt /tmp/out oder mv 'Quarterly Report *.txt' /tmp/out wurde. Halten Sie xtrace von Geheimnissen fern.

Für eine sicherere manuelle Überprüfung geben Sie Werte mit %q aus:

printf 'file=%q\n' "$file" >&2
printf 'target_dir=%q\n' "$target_dir" >&2

%q macht Leerzeichen und Sonderzeichen auf eine Weise sichtbar, die einfacher zu lesen ist als einfaches echo.

Eine praktische Checkliste

Wenn eine Bash-Variable falsch expandiert, überprüfen Sie diese in der Reihenfolge:

1. Läuft das Skript unter Bash, nicht sh?
2. Ist die Variable tatsächlich gesetzt? Verwenden Sie ${VAR:?message} für erforderliche Werte.
3. Ist jede Expansion in Anführungszeichen gesetzt, es sei denn, die Aufteilung ist beabsichtigt?
4. Verwenden Sie ein Array für mehrere Argumente?
5. Hat eine Pipeline Ihre Schleife in eine Subshell gebracht?
6. Hat eine Funktion eine globale Variable überschrieben, weil local fehlte?
7. Werden geschweifte Klammern benötigt, um den Variablennamen von nahem Text zu trennen?

Diese Überprüfungen sind auf die beste Weise langweilig. Sie verwandeln die meisten Expansionsfehler von „Bash ist komisch“ in eine spezifische, behebbare Regel.

Indirekte Expansion und Namerefs erfordern besondere Vorsicht

Bash kann eine Variable expandieren, deren Name in einer anderen Variable gespeichert ist:

name=APP_ENV
printf '%s\n' "${!name}"

Dies gibt den Wert von APP_ENV aus. Es ist mächtig, aber es macht Skripte schwerer lesbar und kann unsicher werden, wenn der Variablenname von Benutzereingaben stammt. Wenn Sie nur eine Zuordnung von Namen zu Werten benötigen, ist ein assoziatives Array klarer:

declare -A endpoints=(
  [dev]='https://dev.example.test'
  [prod]='https://api.example.com'
)

printf '%s\n' "${endpoints[$env]:?unknown environment}"

Bash hat auch Namerefs mit declare -n, die oft in Hilfsfunktionen verwendet werden. Sie sind in bibliotheksartigen Skripten nützlich, aber sie können überraschende Nebeneffekte erzeugen. Verwenden Sie sie nur, wenn das Übergeben eines Arrays oder einer Variable per Referenz den Code wirklich vereinfacht.

Musterentfernung ist kein regulärer Ausdrucksabgleich

Parameterexpansionsoperatoren wie ${file%.log} und ${path##*/} verwenden Shell-Muster, keine regulären Ausdrücke. Dieser Unterschied ist wichtig.

file='access.log'
printf '%s\n' "${file%.log}"

Dies entfernt ein .log-Suffix. Es bedeutet nicht „alles entfernen, was einem Regex entspricht“. Für Regex-Überprüfungen verwenden Sie [[ ... =~ ... ]]:

if [[ $port =~ ^[0-9]+$ ]]; then
  printf 'numeric\n'
fi

Auch hier vorsichtig mit Anführungszeichen. Die rechte Seite von =~ wird normalerweise ohne Anführungszeichen gelassen, wenn sie als Regex behandelt werden soll. Die linke Variable sollte innerhalb von [[ ]] keine Anführungszeichen benötigen, da [[ ]] keine Wortaufteilung wie [ ] durchführt.

Exportieren Sie nur, was Kindprozesse benötigen

Das Setzen einer Variable in Bash macht sie nicht automatisch für Befehle verfügbar, die das Skript startet:

APP_ENV=prod
./run-app

run-app wird APP_ENV nicht sehen, es sei denn, es wird exportiert oder inline bereitgestellt:

export APP_ENV=prod
./run-app

# oder
APP_ENV=prod ./run-app

Dies ist eine häufige Quelle von Verwirrung, wenn ein Skript den richtigen Wert ausgibt, aber ein Kindprozess sich verhält, als ob der Wert fehlt. Die Variable existiert in der Shell; sie wurde nie in die Umgebung für das Kind gesetzt.

Das Gegenteil ist auch wahr: Ein Kindprozess kann die Variablen der übergeordneten Shell nicht ändern. Wenn ein Hilfsskript export TOKEN=... ausgibt, wird das normale Ausführen den Aufrufer nicht aktualisieren. Sie müssten es sourcen, und Sourcing sollte vertrauenswürdigem Shell-Code vorbehalten sein.

Ein echter Review-Durchlauf vor dem Versand

Bevor Sie ein Skript oder eine Container-Einrichtung als abgeschlossen bezeichnen, lesen Sie es einmal so, als wären Sie die nächste Person, die es um 2 Uhr morgens debuggen muss. Das ändert, was Ihnen auffällt. Eine Eingabeaufforderung, die beim Schreiben des Skripts sinnvoll war, kann in einem CI-Protokoll mehrdeutig sein. Ein Docker-Dienstname, der offensichtlich schien, stimmt möglicherweise nicht mit dem Variablennamen in der Anwendung überein. Ein Bash-Standardwert kann für die Entwicklung sicher und für die Produktion gefährlich sein.

Ich mache gerne einen kurzen Trockentest mit bewusst ungünstigen Werten. Verwenden Sie einen Pfad mit Leerzeichen. Verwenden Sie einen leeren optionalen Wert. Versuchen Sie einen Dateinamen, der mit einem Bindestrich beginnt. Führen Sie das Skript aus einem anderen Arbeitsverzeichnis aus. Starten Sie den Container ohne eine erwartete Umgebungsvariable. Diese Tests sind nicht ausgefallen, aber sie fangen die Annahmen, die normalerweise zuerst brechen.

Überprüfen Sie auch die Fehlermeldung. Wenn die einzige Ausgabe failed ist, hat der Rat des Artikels den Weg in die Implementierung nicht gefunden. Ein nützlicher Fehler sagt, welcher Wert verwendet wurde, welche Prüfung fehlgeschlagen ist und was der Bediener ändern kann. Das bedeutet nicht, jede Umgebungsvariable auszugeben oder Geheimnisse zu drucken. Es bedeutet, dort spezifisch zu sein, wo Spezifität hilft: der Konfigurationspfad, der fehlende Befehlsname, der Netzwerkname, der Dienst-Hostname oder der Port, den der Prozess zu binden versuchte.

Die letzte Gewohnheit ist, Beispiele nahe an der Art und Weise zu halten, wie das System tatsächlich ausgeführt wird. Wenn die Produktion Compose verwendet, testen Sie mit Compose. Wenn ein Skript von systemd gestartet wird, testen Sie es mit systemd oder einer ähnlich minimalen Umgebung. Wenn ein Befehl zum Kopieren und Einfügen sicher sein soll, fügen Sie die Anführungszeichen, ---Trennzeichen und Validierung im Beispiel selbst ein. Leser kopieren funktionierende Muster häufiger als Warnungen.

Dieser Review-Durchlauf ist keine Bürokratie. Es ist, wie kleine Automatisierung langweilig bleibt. Langweilig ist, was Sie von Shell-Eingabeaufforderungen, Konfigurationsladern, Variablenexpansion, Container-Diagnose und Docker-Netzwerken wollen. Je weniger überraschend das Verhalten ist, desto einfacher ist es für den nächsten Bediener, ihm zu vertrauen.

Fügen Sie für die Variablenexpansion eine weitere Gewohnheit zu diesem Review hinzu: Geben Sie die Argumentanzahl aus, wenn sich ein Befehl seltsam verhält. Ein kleiner Helfer kann das Unsichtbare sichtbar machen:

show_args() {
  local i=1
  for arg in "$@"; do
    printf 'arg[%d]=%q\n' "$i" "$arg" >&2
    i=$((i + 1))
  done
}

show_args mv $file $target_dir
show_args mv "$file" "$target_dir"

Der erste Aufruf zeigt, was der kaputte Befehl erhalten würde; der zweite zeigt die korrigierte Version. Sobald Sie die Argumentliste sehen, hören Anführungszeichenfehler auf, mysteriös zu sein.