Bash 스크립트 실패 시 체계적인 문제 해결 접근법

Bash 스크립트 실패 문제 해결은 한 가지 질문으로 시작합니다: 명령어가 잘못되었거나, 환경이 달랐거나, 입력이 예상과 달라서 스크립트가 실패했습니까? 반복 가능한 디버깅 루틴은 크론 작업, 배포 훅 또는 백업 스크립트가 중단될 때 추측을 방지합니다.

아래 단계를 사용하여 실패 신호를 읽고, Bash가 실제로 실행한 내용을 추적하며, 문제를 특정 명령어로 좁혀보세요.

1단계: 준비 및 초기 평가

복잡한 디버깅 플래그를 사용하기 전에 기본 요소가 갖춰져 있는지 확인하세요. 구조화된 초기 평가는 상당한 시간을 절약해 줍니다.

1. 오류 메시지 및 종료 코드 검토

가장 즉각적인 단서는 셸이 보고한 오류 메시지입니다. 제공된 경우 언급된 줄 번호에 주의하세요.

종료 코드: 셸 스크립팅에서 특수 변수 $?는 가장 최근에 실행된 포그라운드 명령어의 종료 상태를 보유합니다. 성공적인 명령어는 0을 반환합니다. 0이 아닌 값은 실패를 나타냅니다.
```
some_command
echo "명령어가 상태로 종료됨: $?"
# $?가 127이면 종종 "명령어를 찾을 수 없음"을 의미합니다.
```

2. 스크립트 실행 모드 확인

스크립트가 의도한 대로 실행되고 있는지, 특히 shebang 줄로 지정된 인터프리터와 관련하여 확인하세요.

Shebang: 인터프리터를 정의하려면 항상 적절한 shebang 줄로 스크립트를 시작하세요. #!/bin/bash가 표준이지만, 이식성을 위해 #!/usr/bin/env bash가 종종 선호됩니다.
권한: 스크립트에 실행 권한이 설정되어 있는지 확인하세요:
```
chmod +x your_script.sh
```

3. 실행 환경 격리

환경 차이는 간헐적 실패의 주요 원인입니다. 항상 스크립트가 실행되어야 하는 환경에서 테스트하거나 개발과 프로덕션 간에 다른 변수를 확인하세요.

직접 테스트: 이름으로만 실행할 때 잠재적인 PATH 문제를 우회하여 인터프리터를 사용해 스크립트를 직접 실행하세요:
```
/bin/bash ./your_script.sh
```

2단계: Bash 디버깅 플래그 활성화

Bash는 실행 흐름과 변수 평가를 추적할 수 있는 강력한 내장 플래그를 제공하며, 이는 논리 오류나 예상치 못한 확장을 정확히 찾는 데 중요합니다.

1. 필수 디버깅 플래그

이러한 플래그는 일반적으로 shebang 줄에 추가되거나 set을 사용하여 스크립트 내에서 활성화/비활성화됩니다.

플래그	명령어	목적
-n	`set -n`	명령어를 읽지만 실행하지 않음 (구문 검사만).
-v	`set -v`	읽은 대로 셸 입력 줄을 출력 (자세한 모드).
-x	`set -x`	실행된 대로 명령어와 인수를 출력 (추적 모드). 논리 오류에 가장 강력함.

2. 추적 모드 사용 (`set -x`)

set -x는 실행된 모든 명령어의 출력 앞에 + 기호를 붙여 변수 확장을 포함하여 Bash가 해석하는 내용을 정확히 보여줍니다.

추적 예시:

잘못된 인용으로 인해 실패하는 스크립트를 고려해보세요:

# 원본 스크립트 스니펫
USER_INPUT="Hello World"
echo $USER_INPUT  # USER_INPUT에 공백이 포함되어 다른 명령어에 전달된 경우 실패

set -x가 활성화된 상태로 실행할 때 (#!/bin/bash -x 또는 시작 부분에 set -x 사용):

+ USER_INPUT='Hello World'
+ echo Hello World
Hello World

인용 문제가 의심되면 문제가 있는 부분 주위에 선택적으로 추적 모드를 활성화할 수 있습니다:

set -x
# 잘 작동하는 명령어들

# 문제가 있는 부분만 추적
COMMAND_THAT_FAILS_DUE_TO_EXPANSION
set +x
# 나머지 스크립트

모범 사례: 전체 스크립트를 디버깅하려면 #!/bin/bash -x를 사용하거나 shebang 바로 뒤에 set -x를 배치하세요.

3. 변수 확장 디버깅

많은 실패는 변수가 어떻게 확장되는지(또는 확장되지 않는지)에서 비롯됩니다. 단어 분할 및 글로브 확장을 방지하기 위해 변수 주위에 큰따옴표를 자유롭게 사용하되("$VAR"), 추적(set -x)을 사용하여 확장이 예상대로 발생하는지 확인하세요.

공백을 포함한 변수의 리터럴 값을 보려면 구분 기호로 둘러싸고 인용하여 에코할 수 있습니다:

VAR="a b c"
printf '[%s]\n' "$VAR"
# 출력: [a b c]

3단계: 일반적인 오류 유형 처리

디버깅 플래그가 활성화되면 오류는 일반적으로 예측 가능한 범주로 나뉩니다.

1. 명령어를 찾을 수 없음 (종료 코드 127)

종종 your_command: command not found로 나타나는 이 오류는 셸이 실행 파일을 찾을 수 없음을 나타냅니다.

PATH 확인: 명령어가 포함된 디렉토리가 스크립트 실행 컨텍스트 내의 $PATH 환경 변수에 나열되어 있는지 확인하세요.
절대 경로 사용: 확실하지 않은 경우 명령어의 전체 경로를 사용하세요 (예: curl 대신 /usr/bin/curl).

2. 구문 오류

이러한 오류는 종종 일치하지 않는 구분 기호, 제어 구조(if, for, while)의 잘못된 사용, 또는 누락된 세미콜론/줄 바꿈을 포함합니다.

set -n (실행 안 함): set -n으로 스크립트를 실행하면 Bash가 실행 없이 모든 것을 구문 분석하도록 강제하여 닫히지 않은 대괄호나 누락된 fi/done 문을 즉시 드러냅니다.
조건문 구문: [[ ... ]]와 [ ... ]의 차이에 주의하세요. 예를 들어, 산술 연산을 테스트하려면 표준 테스트 구조가 아닌 (( ... )) 또는 let이 필요합니다.

예시 (산술 컨텍스트):
```
# A가 B보다 큰지 확인하는 올바른 방법
A=10
B=5
if (( A > B )); then
    echo "A가 더 큽니다"
fi
```

3. 권한 및 입출력 문제

스크립트가 실행되지만 파일이나 외부 프로세스와 상호 작용할 때 실패하는 경우 권한과 파일 디스크립터를 확인하세요.

입력 리디렉션: 파일에서 입력을 리디렉션하는 경우 해당 파일이 존재하고 읽을 수 있는지 확인하세요.
출력 리디렉션: 대상 디렉토리가 존재하고 스크립트 사용자에게 쓰기 권한이 있는지 확인하세요.

SUDO에 대한 경고: sudo로 스크립트를 실행하면 $PATH와 같은 환경 변수와 사용자별 구성(예: .bashrc)이 종종 재설정되거나 변경됩니다. 일반 사용자로 실행할 때 작동하는 명령어가 누락된 컨텍스트나 경로로 인해 sudo 아래에서 실패할 수 있습니다.

4단계: 로깅 및 시스템 점검

백그라운드에서 실행되는 스크립트(예: Cron을 통해)의 경우 직접 터미널 출력을 사용할 수 없습니다. 강력한 로깅이 필수적입니다.

1. 디버깅을 위한 출력 리디렉션

무인 실행 시 표준 출력(stdout, 디스크립터 1)과 표준 오류(stderr, 디스크립터 2)를 모두 로그 파일로 리디렉션하세요. 결합하는 것이 일반적입니다:

# 모든 출력을 debug.log로 리디렉션
./your_script.sh >> debug.log 2>&1

set -x를 사용하는 경우 추적 출력이 동일한 로그 파일로 이동하여 실행 흐름과 오류의 완전한 기록을 제공합니다.

2. 시스템 상태 확인

때로는 스크립트 자체는 괜찮지만 시스템 환경이 문제인 경우가 있습니다:

디스크 공간: 시스템에 디스크 공간이 부족합니까 (df -h)? 이는 쓰기 작업을 중단시킵니다.
메모리: 메모리 사용량을 확인하세요 (free -m). 높은 메모리 압력은 외부 명령어가 실패하거나 중단되게 할 수 있습니다.
Cron 환경: Cron을 통해 예약된 경우 Cron 작업은 매우 제한된 환경에서 실행된다는 점을 기억하세요. Cron 작업 설정에 의해 보장되지 않는 경우 스크립트 상단에 필요한 환경 변수를 항상 명시적으로 정의하세요.

디버깅 경로를 짧게 유지하세요

Bash 스크립트가 실패하면 먼저 종료 코드와 정확한 오류를 캡처하세요. 그런 다음 shebang, 권한, $PATH, 입력 파일 및 사용자 컨텍스트를 확인하세요. 원인이 여전히 불분명하면 의심스러운 블록 주위에서만 set -x를 활성화하고 무인 출력을 로그로 보내세요.

이 순서는 문제 해결을 실용적으로 유지합니다. 가장 명확한 증거에서 가장 상세한 추적으로 이동하여 노이즈에 압도되지 않습니다.