Trampas de cmd.exe y de los scripts batch: momento de evaluación de %ERRORLEVEL%, expansión retardada y escape con el acento circunflejo

Qué es

El modelo de scripting de cmd.exe es anterior a PowerShell y mantiene sus propias reglas para condicionales, expansión de variables y escape de caracteres. Estas reglas están documentadas en la referencia Windows Commands de Microsoft, en las páginas de if y setlocal.

Por qué importa

• %ERRORLEVEL% frente a if errorlevel: %ERRORLEVEL% es una expansión normal, igual que la de las variables de entorno, y se sustituye una sola vez, cuando se analiza la línea. Dentro de un bloque if/for de varias líneas (que se analiza como una sola unidad) puede mostrar el valor previo a la ejecución del bloque y no el que dejó un comando interno. En cambio, if errorlevel N (documentado en la misma página de referencia de if) comprueba si «la variable ERRORLEVEL es igual o mayor que N» ("is the ERRORLEVEL variable equal to or greater than N"), y lo evalúa en el momento en que se ejecuta el if. Por eso es la comprobación más segura para saber si el comando externo anterior falló.
• Expansión retardada: setlocal EnableDelayedExpansion habilita la sintaxis !var!, que se evalúa cuando cada línea se ejecuta realmente y no cuando se analizó el bloque (%var% sigue evaluándose al analizar). Sin ella, un bucle que asigna y lee la misma variable dentro de un bloque solo ve el valor anterior al bucle. La página de setlocal de Windows Commands documenta este modificador. Mientras está activo, un ! literal en los datos (una contraseña, un nombre de archivo) se interpreta como sintaxis de expansión y desaparece.
• Comillas y acento circunflejo: cmd.exe no admite el entrecomillado con comillas simples. El acento circunflejo (^) es el carácter de escape para los caracteres que cmd trata de forma especial (& | < > ^, y ( ) dentro de bloques). El % se escapa duplicándolo (%%) en un archivo batch, no con el acento circunflejo. Dentro de "..." esos caracteres pierden su significado especial (allí el acento circunflejo es literal). El fallo clásico es concatenar en una línea sin comillas una URL o una ruta que contiene &.
• Llamar a herramientas de cmd.exe o batch desde PowerShell: PowerShell vuelve a analizar los argumentos, de modo que una línea cmd.exe /c con comillas incrustadas o con &/| suele necesitar el token de detención del análisis --%. about_Parsing lo documenta como un cambio en "the interpretation of all remaining arguments" (la interpretación de todos los argumentos restantes): PowerShell pasa el resto de la línea de forma literal, sigue expandiendo las variables de entorno %NAME%, no admite variables de PowerShell y se detiene en el siguiente salto de línea o carácter de canalización. Está pensado para comandos nativos en Windows.

Cómo aplicarlo

• Es preferible usar if errorlevel 1 (...) o if %ERRORLEVEL% neq 0 (...) justo después del comando que se comprueba, y no dentro de un bloque que también modifique el valor (en ese caso, usar !ERRORLEVEL!). if errorlevel 1 significa «1 o superior» y no detecta códigos de salida negativos, como los de un fallo abrupto; neq 0 detecta cualquier error.
• Usar setlocal EnableDelayedExpansion y !var! siempre que una variable se asigne y se vuelva a leer dentro de un mismo bloque entre paréntesis.
• Encerrar entre comillas dobles cualquier valor que pueda contener &, |, <, >, ^ o espacios; cuando no sea posible entrecomillar, escapar el carácter con un acento circunflejo.
• Desde PowerShell, usar cmd.exe /c --% <literal command> para líneas de comandos con caracteres que PowerShell reinterpretaría de otro modo.

Trampas

• Comprobar %ERRORLEVEL% más tarde que justo después del comando: otro programa externo lo sobrescribe, mientras que muchos comandos internos como echo lo dejan intacto, por lo que puede sobrevivir un valor obsoleto de un comando anterior. Nunca se debe usar set ERRORLEVEL=..., que oculta el valor dinámico.
• Mezclar expansión retardada y no retardada para la misma variable en un script, de modo que %var% y !var! discrepen sobre cuál es el valor vigente.
• Suponer que batch admite here-strings o arrays; la lógica compleja es señal de que conviene pasar a PowerShell en lugar de anidar más trucos con for /f.