Armadilhas do cmd.exe e de scripts batch: momento de avaliação do %ERRORLEVEL%, expansão atrasada e escape com circunflexo

O que é

O modelo de scripts do cmd.exe é anterior ao PowerShell e mantém regras próprias para condicionais, expansão de variáveis e escape, descritas na referência Windows Commands da Microsoft para if e setlocal.

Por que importa

• %ERRORLEVEL% versus if errorlevel: %ERRORLEVEL% é uma expansão comum, no estilo de variável de ambiente, substituída uma única vez quando a linha é analisada. Dentro de um bloco if/for de várias linhas (analisado como uma unidade só), ele pode mostrar o valor de antes da execução do bloco, e não o resultado de um comando interno. Já if errorlevel N (documentado na mesma página de referência do if) testa "is the ERRORLEVEL variable equal to or greater than N" (se a variável ERRORLEVEL é igual ou maior que N), avaliado no momento em que o if é executado, e é a verificação mais segura para saber se o comando externo anterior falhou.
• Expansão atrasada: setlocal EnableDelayedExpansion habilita a sintaxe !var!, avaliada quando cada linha é de fato executada e não quando o bloco foi analisado (%var% continua sendo avaliada na análise). Sem isso, um laço que atribui e lê a mesma variável dentro de um bloco enxerga apenas o valor anterior ao laço. A página setlocal de Windows Commands documenta essa opção. Enquanto ela estiver ativa, um ! literal em dados (uma senha, um nome de arquivo) é consumido como sintaxe de expansão.
• Aspas e circunflexo: o cmd.exe não reconhece aspas simples como delimitadores; o circunflexo (^) é o caractere de escape para os caracteres que o cmd trata de forma especial (& | < > ^ e, dentro de blocos, ( )); o % é escapado dobrando-o (%%) em um arquivo batch, e não com circunflexo. Dentro de "..." esses caracteres perdem o significado especial (um circunflexo ali é literal); uma URL ou caminho contendo & concatenado em uma linha sem aspas é a falha clássica.
• Chamar cmd.exe/ferramentas batch a partir do PowerShell: o PowerShell reanalisa os argumentos, então uma linha cmd.exe /c com aspas embutidas ou &/| costuma exigir o token de parada de análise --%, que about_Parsing documenta como alteração de "the interpretation of all remaining arguments" (a interpretação de todos os argumentos restantes): o PowerShell passa o resto da linha literalmente, ainda expande variáveis de ambiente %NAME%, não permite variáveis do PowerShell e termina na próxima quebra de linha ou caractere de pipe. Ele se destina a comandos nativos no Windows.

Como aplicar

• Prefira if errorlevel 1 (...) ou if %ERRORLEVEL% neq 0 (...) colocado imediatamente após o comando que verifica, e não dentro de um bloco que também altera o valor (nesse caso, use !ERRORLEVEL!). if errorlevel 1 significa "1 ou maior" e não detecta códigos de saída negativos, como os de falha fatal; neq 0 pega qualquer falha.
• Use setlocal EnableDelayedExpansion e !var! sempre que uma variável for atribuída e lida de novo dentro de um mesmo bloco entre parênteses.
• Coloque entre aspas duplas qualquer valor que possa conter &, |, <, >, ^ ou espaços; quando não for possível usar aspas, escape o caractere com um circunflexo.
• No PowerShell, use cmd.exe /c --% <literal command> para linhas de comando com caracteres que o PowerShell reinterpretaria.

Armadilhas

• Verificar %ERRORLEVEL% depois do momento imediatamente posterior ao comando: outro programa externo o sobrescreve, enquanto muitos comandos internos, como echo, o deixam inalterado, de modo que um valor desatualizado de um comando anterior pode sobreviver. Nunca use set ERRORLEVEL=..., que oculta o valor dinâmico.
• Misturar expansão atrasada e não atrasada para a mesma variável em um script, de modo que %var% e !var! discordem sobre qual é o valor atual.
• Presumir que o batch suporta here-strings ou arrays; lógica complexa é sinal de que é hora de migrar para o PowerShell, em vez de aninhar mais truques com for /f.