Quando Seu Script Bash Falha: Uma Abordagem Sistemática de Solução de Problemas

A solução de problemas de falha de script Bash começa com uma pergunta: o script falhou porque o comando estava errado, o ambiente era diferente ou a entrada não era o que você esperava? Uma rotina de depuração repetível impede que você fique adivinhando quando um cron job, hook de implantação ou script de backup quebra.

Use as etapas abaixo para ler o sinal de falha, rastrear o que o Bash realmente executou e restringir o problema a um comando específico.

Fase 1: Preparação e Avaliação Inicial

Antes de mergulhar em flags de depuração complexas, certifique-se de ter os elementos fundamentais em vigor. Uma avaliação inicial estruturada economiza um tempo significativo.

1. Revise a Mensagem de Erro e o Código de Saída

A pista mais imediata é a mensagem de erro relatada pelo shell. Preste muita atenção ao número da linha mencionado, se fornecido.

Códigos de Saída: Em scripts de shell, a variável especial $? contém o status de saída do comando em primeiro plano executado mais recentemente. Um comando bem-sucedido retorna 0. Qualquer valor diferente de zero indica falha.
```
some_command
echo "Comando encerrou com status: $?"
# Se $? for 127, geralmente significa "comando não encontrado".
```

2. Verifique o Modo de Execução do Script

Certifique-se de que o script está sendo executado conforme o esperado, especialmente em relação ao interpretador especificado pela linha shebang.

Shebang: Sempre inicie seu script com uma linha shebang adequada para definir o interpretador. #!/bin/bash é padrão, mas #!/usr/bin/env bash é frequentemente preferido para portabilidade.
Permissões: Confirme se o script tem permissões de execução definidas:
```
chmod +x seu_script.sh
```

3. Isole o Ambiente de Execução

Diferenças de ambiente são uma grande fonte de falhas intermitentes. Sempre teste no ambiente onde o script deve ser executado, ou confirme variáveis que diferem entre desenvolvimento e produção.

Teste Diretamente: Execute o script diretamente usando o interpretador, contornando possíveis problemas de PATH se executar apenas pelo nome:
```
/bin/bash ./seu_script.sh
```

Fase 2: Ativando Flags de Depuração do Bash

O Bash fornece flags internas poderosas que podem rastrear o fluxo de execução e a avaliação de variáveis, cruciais para identificar erros de lógica ou expansão inesperada.

1. As Flags de Depuração Essenciais

Essas flags são normalmente adicionadas à linha shebang ou ativadas/desativadas dentro do script usando set.

Flag	Comando	Propósito
-n	`set -n`	Lê comandos mas não os executa (apenas verificação de sintaxe).
-v	`set -v`	Imprime linhas de entrada do shell conforme são lidas (modo verboso).
-x	`set -x`	Imprime comandos e seus argumentos conforme são executados (modo de rastreamento). Este é o mais poderoso para erros de lógica.

2. Usando o Modo de Rastreamento (`set -x`)

set -x prefixa a saída de cada comando executado com um sinal +, mostrando exatamente o que o Bash está interpretando, incluindo expansões de variáveis.

Exemplo de Rastreamento:

Considere um script que falha devido a aspas incorretas:

# Trecho do Script Original
USER_INPUT="Hello World"
echo $USER_INPUT  # Falha se USER_INPUT contivesse espaços e fosse passado para outro comando

Ao executar com set -x ativado (seja via #!/bin/bash -x ou set -x no início):

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

Se você suspeitar de problemas com aspas, pode ativar o modo de rastreamento seletivamente ao redor da seção problemática:

set -x
# Comandos que funcionam bem

# Rastreie apenas a seção problemática
COMANDO_QUE_FALHA_DEVIDO_A_EXPANSAO
set +x
# Resto do script

Melhor Prática: Para depurar o script inteiro, use #!/bin/bash -x ou coloque set -x imediatamente após o shebang.

3. Depurando a Expansão de Variáveis

Muitas falhas decorrem de como as variáveis são expandidas (ou não). Use aspas duplas liberalmente ao redor das variáveis ("$VAR") para evitar divisão de palavras e expansão de glob, mas use o rastreamento (set -x) para ver se a expansão está ocorrendo conforme o esperado.

Se você quiser ver o valor literal de uma variável incluindo espaços em branco, pode ecoá-la entre aspas e cercada por delimitadores:

VAR="a b c"
printf '[%s]\n' "$VAR"
# Saída: [a b c]

Fase 3: Lidando com Tipos Comuns de Erro

Uma vez que as flags de depuração estão ativas, os erros geralmente se enquadram em categorias previsíveis.

1. Comando Não Encontrado (Código de Saída 127)

Este erro, frequentemente aparecendo como seu_comando: comando não encontrado, indica que o shell não consegue localizar o executável.

Verifique o PATH: Certifique-se de que o diretório que contém o comando está listado na variável de ambiente $PATH dentro do contexto de execução do script.
Use Caminhos Absolutos: Em caso de dúvida, use o caminho completo para o comando (por exemplo, /usr/bin/curl em vez de apenas curl).

2. Erros de Sintaxe

Estes geralmente envolvem delimitadores incompatíveis, uso incorreto de estruturas de controle (if, for, while), ou ponto e vírgula/quebras de linha ausentes.

set -n (Sem Execução): Executar o script com set -n força o Bash a analisar tudo sem executar, frequentemente revelando colchetes não fechados ou instruções fi/done ausentes imediatamente.
Sintaxe Condicional: Preste muita atenção a [[ ... ]] vs [ ... ]. Por exemplo, testar aritmética requer (( ... )) ou let, não estruturas de teste padrão.

Exemplo (Contexto Aritmético):
```
# Maneira correta de verificar se A é maior que B
A=10
B=5
if (( A > B )); then
    echo "A é maior"
fi
```

3. Problemas de Permissões e Entrada/Saída

Se o script for executado mas falhar ao interagir com arquivos ou processos externos, verifique permissões e descritores de arquivo.

Redirecionamento de Entrada: Se você está redirecionando a entrada de um arquivo, certifique-se de que o arquivo existe e é legível.
Redirecionamento de Saída: Verifique se o diretório de destino existe e se o usuário do script tem permissões de escrita.

Aviso sobre SUDO: Se você executar um script com sudo, variáveis de ambiente como $PATH e configurações específicas do usuário (como .bashrc) são frequentemente redefinidas ou alteradas. Comandos que funcionam quando executados como um usuário normal podem falhar sob sudo devido a contexto ou caminhos ausentes.

Fase 4: Registro em Log e Verificações do Sistema

Para scripts executados em segundo plano (por exemplo, via Cron), a saída direta do terminal não está disponível. Um registro robusto é essencial.

1. Redirecionando a Saída para Depuração

Ao executar de forma não supervisionada, redirecione tanto a saída padrão (stdout, descritor 1) quanto o erro padrão (stderr, descritor 2) para um arquivo de log. Combiná-los é comum:

# Redireciona toda a saída para debug.log
./seu_script.sh >> debug.log 2>&1

Se estiver usando set -x, a saída de rastreamento irá para o mesmo arquivo de log, fornecendo um registro completo do fluxo de execução e erros.

2. Verificando a Saúde do Sistema

Às vezes, o script em si está bem, mas o ambiente do sistema é o problema:

Espaço em Disco: O sistema está ficando sem espaço em disco (df -h)? Isso interromperá operações de escrita.
Memória: Verifique o uso de memória (free -m). Alta pressão de memória pode fazer com que comandos externos falhem ou travem.
Ambiente Cron: Se agendado via Cron, lembre-se de que os jobs Cron são executados com um ambiente altamente restrito. Sempre defina explicitamente as variáveis de ambiente necessárias no topo do script se elas não forem garantidas pela configuração do job Cron.

Mantenha o Caminho de Depuração Curto

Quando seu script Bash falhar, capture o código de saída e o erro exato primeiro. Em seguida, confirme o shebang, permissões, $PATH, arquivos de entrada e contexto do usuário. Se a causa ainda não estiver clara, ative set -x apenas ao redor do bloco suspeito e envie a saída não supervisionada para um log.

Essa ordem mantém a solução de problemas prática. Você passa da evidência mais clara para o rastreamento mais detalhado sem se inundar de ruído.