Escapar JSON en una línea: cómo convertir y pegar sin errores

Contenido
Que un JSON de varias líneas se rompa cuando lo pegas tal cual en un argumento de CLI o en el valor de un archivo .env se debe a que unos cuantos caracteres —la barra invertida, las comillas dobles y los saltos de línea— chocan con la gramática del destino.
Si sustituyes cada uno de esos caracteres por su secuencia de escape correspondiente, obtienes una cadena segura de una sola línea que conserva el contenido original intacto. Este artículo explica esas reglas de sustitución carácter por carácter.
Resumen ① Si metes el JSON tal cual en un argumento de CLI o en un valor de
.env, las barras invertidas, las comillas dobles y los saltos de línea chocan con la gramática del destino y todo se rompe. ② El modo “Escapar JSON” valida con JSON.parse y después minifica en una sola línea; el modo “Escapar texto sin procesar (Raw)” escapa la entrada tal cual, sin validar. ③ Las comillas dobles, los saltos de línea y las tabulaciones vienen activados por defecto y las comillas simples desactivadas, así que si cambias las casillas la misma entrada produce una cadena distinta.
Por qué se rompe el JSON si lo pegas tal cual en un argumento de CLI o en un valor de .env
Piensa en una situación habitual: tienes un JSON que has recibido de una respuesta de API o de un archivo de configuración y lo pegas tal cual en un archivo .env, justo detrás de APP_CONFIG=. El JSON original es un texto de varias líneas, con saltos de línea y sangría, pensado para que una persona lo lea cómodamente.
Si metes ese texto tal cual donde se espera un valor de una sola línea, se rompe en tres puntos.
- Saltos de línea: un archivo
.envo una variable de shell leen una línea como un único valor. Si hay un salto de línea real en medio del valor, el valor se corta justo ahí. - Comillas dobles: lo habitual es envolver todo el valor entre comillas dobles, pero dentro del JSON también hay comillas dobles por todas partes. En cuanto el parser se encuentra con una comilla interior, interpreta que el valor ha terminado.
- Argumentos de CLI entre comillas simples: si un valor de cadena del JSON contiene un apóstrofo ('), el shell POSIX no tiene forma de escapar una comilla simple dentro de comillas simples, así que el argumento se cierra en ese punto.
Por eso, cualquier destino que exija meter el JSON en una cadena de una sola línea —argumentos de CLI, valores de .env, campos de cadena anidados dentro de otro JSON, literales de cadena en el código fuente— plantea en el fondo la misma regla.
Los caracteres de control como los saltos de línea y las tabulaciones se convierten en una secuencia visible, y delante de las comillas que hacen de delimitador y de la propia barra invertida que sirve para escapar hay que poner otra barra invertida, para indicar “este carácter no es un signo de la gramática, es simplemente dato”.
Cómo escapar a mano, sin ninguna herramienta
Las reglas de escape no son ningún secreto que solo conozca un programa concreto: son una tabla de sustitución de caracteres común que siguen JSON.stringify y la mayoría de los lenguajes.
Si ejecutas el siguiente código en la consola de las herramientas de desarrollo del navegador, puedes reproducir a mano el mismo resultado que da la herramienta que describe este artículo.
Para validar la sintaxis JSON y además minificar, hazlo así.
// Paso 1: validar la sintaxis JSON y minificar en una sola línea (quitar sangría y saltos de línea)
const minified = JSON.stringify(JSON.parse(rawInput));
// Paso 2: sustituir caracteres. Hay que sustituir la barra invertida primero, para evitar
// que las barras invertidas que añadimos después se vuelvan a sustituir.
const escaped = minified
.replace(/\\/g, "\\\\") // barra invertida → \\
.replace(/"/g, '\\"') // comilla doble → \" (opcional)
.replace(/\n/g, "\\n") // salto de línea → \n (opcional)
.replace(/\t/g, "\\t"); // tabulación → \t (opcional)
Cuando rawInput no tenga por qué ser JSON válido, es decir, cuando quieras escapar tal cual un fragmento de log o texto normal, sáltate el paso 1 y aplica directamente la cadena de sustituciones del paso 2 a la cadena original.
Eso es todo lo que hace el modo “Escapar texto sin procesar (Raw)”.
Si envuelves el resultado entre comillas dobles y lo pegas en un argumento de CLI o en un valor de .env, se transmite en una sola línea conservando el significado del JSON original.
Compruébalo con nuestra herramienta.
Con JSON se valida y se comprime en una línea; el texto plano se escapa tal cual, sin validar. Es gratis, sin instalación ni registro.

Las dudas más habituales
La diferencia entre los dos modos, resumida en una tabla, es esta.
| Aspecto | Modo Escapar JSON | Modo Escapar texto sin procesar (Raw) |
|---|---|---|
| Validación con JSON.parse | Sí (muestra un error si falla) | No |
| Minificado (quitar saltos de línea e indentación) | Se minifica con JSON.stringify | Se conserva el original tal cual |
| Entrada con JSON no válido | Muestra el error “No es un JSON válido” | Se procesa igual, sin error |
| A qué se aplica | Solo a texto JSON válido | A cualquier texto |
Por qué el resultado no cambia al marcar o desmarcar las casillas
De las cuatro casillas de opciones de escape, la combinación que realmente cambia el resultado depende del modo.
En el modo “Escapar JSON”, la entrada pasa primero por JSON.stringify, y en ese paso la propia sintaxis JSON ya ha convertido los saltos de línea y las tabulaciones que hay dentro de los valores de cadena en secuencias de dos caracteres como \n y \t.
Por eso, en el modo JSON, las casillas “Escapar saltos de línea” y “Escapar tabulaciones” no cambian el resultado tanto si las marcas como si no: ya no queda ningún salto de línea ni tabulación real que sustituir.
Las comillas dobles, las comillas simples y el modo Raw funcionan de otra manera
Al contrario, “Escapar comillas dobles” sí tiene efecto también en el modo JSON, porque JSON.stringify deja intactas las comillas dobles estructurales que envuelven claves y valores.
“Escapar comillas simples” tampoco la toca JSON.stringify, ya que es un carácter que no existe en la sintaxis JSON; por eso, si el valor contiene apóstrofos, el resultado cambia según el estado de la casilla.
En el modo “Escapar texto sin procesar (Raw)” no se pasa por JSON.stringify, sino que se recorre la entrada carácter a carácter, así que las cuatro opciones se reflejan en el resultado tal como las actives o las desactives.
Además, el modo JSON funciona deserializando con JSON.stringify el valor que ha creado JSON.parse, así que la notación original puede variar ligeramente: por ejemplo, un decimal sin significado como 1.0 se convierte en 1. Si necesitas conservar la notación literal, es más seguro usar el modo Raw.
Cuándo aparece el error “No es un JSON válido”
Este error aparece cuando JSON.parse no consigue interpretar la entrada según la sintaxis JSON. Las causas más frecuentes son estas.
- Que quede una coma después del último elemento (trailing comma)
- Que una clave o un valor de cadena esté entre comillas simples (JSON solo admite comillas dobles)
- Que una clave esté escrita sin comillas
- Que haya comentarios (
//,/* */), que no existen en JSON - Que no coincida el número de llaves o corchetes de apertura y de cierre
Si se cumple cualquiera de estos casos, el modo JSON no genera ningún resultado y solo muestra el error. Si no quieres corregir la sintaxis, cambia al modo “Escapar texto sin procesar (Raw)” y se escapará tal cual, sin validación.
En resumen
- La barra invertida se escapa siempre; las comillas dobles, los saltos de línea y las tabulaciones, por defecto; y las comillas simples, solo si activas la opción.
- El modo “Escapar JSON” valida con
JSON.parsey minifica, pero en ese proceso los saltos de línea y las tabulaciones dentro de los valores de cadena ya se han convertido en\ny\t, así que esas casillas no tienen efecto en el modo JSON. - El modo “Escapar texto sin procesar (Raw)” recorre la entrada carácter a carácter, sin validación ni minificado, así que las cuatro opciones se reflejan en el resultado y también sirve para texto que no es JSON.
- El error “No es un JSON válido” se debe a infracciones de la sintaxis JSON como comas finales, comillas simples o claves sin comillas.
- Las mismas reglas se pueden reproducir a mano solo con
JSON.stringifyy una cadena de sustituciones con expresiones regulares.
Con JSON se valida y se comprime en una línea; el texto plano se escapa tal cual, sin validar. Es gratis, sin instalación ni registro.
Preguntas frecuentes
¿Debo usar el escape de JSON o el escape de texto sin procesar?
Si tu entrada es JSON válido y quieres comprobarlo mientras lo compactas, usa el modo de escape de JSON.
Si no es JSON válido (fragmentos de logs, trozos de código, JSON con la sintaxis rota) o si solo quieres escapar los saltos de línea y la indentación originales sin compactar nada, usa el modo de escape de texto sin procesar.
En el resultado aparecen dos barras invertidas seguidas, ¿es un error?
No, no es un error. Ocurre porque la propia secuencia de escape empieza con una barra invertida ().
Si el original ya contenía una barra invertida, esa barra también se escapa y pasa a ser \\; si además se escapa el carácter que va detrás (por ejemplo, una comilla doble), es normal ver varias barras invertidas seguidas. Cada barra invertida representa un escape distinto, así que el resultado es correcto.
¿Por qué las comillas simples no se escapan de forma predeterminada?
Porque la propia sintaxis de JSON encierra las cadenas solo entre comillas dobles y no le da ningún significado a las comillas simples.
Por eso las comillas dobles, los saltos de línea y los tabuladores están activados por defecto, mientras que las comillas simples quedan desactivadas: solo hacen falta en destinos concretos, como scripts de shell que envuelven los valores entre comillas simples. Si las necesitas, basta con marcar la casilla.
Si voy a usar el resultado en un archivo .env o como argumento de CLI, ¿tengo que añadir las comillas yo mismo?
Sí. Esta herramienta solo sustituye los caracteres dentro de la cadena y no añade las comillas exteriores que envuelven el valor completo. Para usarlo en un archivo .env o como argumento de CLI, tienes que envolver el resultado tú mismo entre comillas dobles (o simples) para que se reconozca como un único valor.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano