Reparar WordPress cuando el tema rompe el editor

Entender el problema: cuando el tema rompe el editor de WordPress

Que el tema de WordPress rompa el editor es uno de los fallos más frustrantes para cualquier administrador o desarrollador. De repente, el editor de entradas o páginas deja de cargar, se queda en blanco, muestra errores JavaScript, o el contenido aparece desmaquetado. En la mayoría de los casos, el origen del problema está en un conflicto de código entre el tema activo y el editor (Gutenberg o editor clásico), o en una carga incorrecta de scripts y estilos.

Este tipo de errores suele aparecer después de actualizar WordPress, cambiar de tema, instalar un tema hijo, modificar functions.php o añadir fragmentos de código personalizados. La buena noticia es que, con un método ordenado, es posible diagnosticar y reparar el problema sin perder contenido ni afectar de forma permanente al sitio en producción.

Síntomas comunes cuando el tema rompe el editor

Antes de tocar archivos del tema conviene identificar con claridad los síntomas. Esto te ayudará a acotar el tipo de error y a buscar la solución adecuada. No todos los fallos del editor tienen el mismo origen, pero cuando el tema está implicado suelen repetirse ciertos patrones.

• La pantalla del editor aparece completamente en blanco (pantalla blanca de la muerte en el admin).
• El editor de bloques no carga y se muestra un mensaje de error crítico.
• El inspector del navegador muestra errores JavaScript relacionados con archivos del tema.
• Los estilos del editor se ven rotos: tipografías, colores o anchos incoherentes.
• El editor clásico muestra solo el modo HTML y no permite cambiar a visual.
• Al activar un tema concreto, el editor deja de funcionar, y al volver a un tema por defecto (Twenty Twenty-*) se soluciona.
• El editor funciona en algunos tipos de contenido (entradas) pero no en otros (páginas, CPT), después de registrar soportes en el tema.

Primeros pasos seguros antes de tocar el tema

Antes de editar archivos del tema o desactivar componentes en un sitio en producción, es fundamental tomar algunas precauciones. Esto reducirá el riesgo de dejar la web inaccesible o de perder cambios importantes.

• Realiza una copia de seguridad completa (archivos + base de datos) usando tu plugin de backup habitual o la herramienta del hosting.
• Trabaja en un entorno de staging siempre que sea posible, clonando el sitio para hacer pruebas sin afectar a los usuarios.
• Anota la configuración actual: tema activo, tema hijo, versiones de WordPress, PHP y plugins.
• Guarda fragmentos de código personalizados que hayas añadido recientemente en functions.php o en archivos del tema.
• Ten acceso FTP o al gestor de archivos del hosting para poder revertir cambios si el panel de WordPress deja de ser accesible.

Activar modo recuperación y depuración en WordPress

Cuando el editor deja de funcionar por un error fatal de PHP o un conflicto grave, WordPress suele activar el modo de recuperación y enviar un correo al administrador. Sin embargo, para diagnosticar problemas más sutiles es recomendable habilitar la depuración manualmente y revisar los registros de errores.

Habilitar WP_DEBUG en wp-config.php

Edita el archivo wp-config.php en la raíz de tu instalación y añade (o ajusta) las siguientes constantes antes de la línea que dice /* That's all, stop editing! */:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Con esta configuración, los errores se registrarán en el archivo wp-content/debug.log sin mostrarse a los visitantes. A continuación, intenta cargar el editor y revisa el log para localizar avisos, warnings o errores fatales relacionados con archivos del tema.

Usar el modo de recuperación de WordPress

Si WordPress detecta un error crítico, mostrará una pantalla de error y enviará un correo con un enlace de acceso seguro al modo de recuperación. Desde ahí podrás desactivar temporalmente el tema o plugins conflictivos sin perder el acceso al panel.

• Accede al enlace de modo recuperación recibido por correo.
• Ve a Apariencia > Temas y cambia temporalmente a un tema por defecto.
• Comprueba si el editor vuelve a funcionar; si es así, confirma que el problema está en el tema original.

Cómo aislar el conflicto: tema vs plugins

No siempre es evidente si el editor se rompe por el tema en sí o por la interacción entre el tema y uno o varios plugins (constructores visuales, plugins de bloques, seguridad, caché, etc.). Para diagnosticarlo, conviene seguir un proceso de aislamiento por pasos.

1. Probar con un tema por defecto

Cambia temporalmente a un tema oficial reciente (por ejemplo, Twenty Twenty-Four):

• Si el editor funciona correctamente con el tema por defecto, el problema está en tu tema o tema hijo.
• Si el editor sigue fallando, es probable que el conflicto esté en un plugin o en la configuración del servidor.

2. Desactivar plugins de forma controlada

Con tu tema activo, desactiva todos los plugins y prueba el editor. Después, ve reactivando uno a uno hasta que el editor vuelva a fallar. El último plugin activado será el principal sospechoso.

3. Revisar el tema hijo frente al tema padre

Si utilizas un tema hijo, activa temporalmente el tema padre original. Si el editor funciona con el tema padre pero no con el hijo, el problema se encuentra en las personalizaciones del tema hijo (normalmente en functions.php, editor-style.css o plantillas personalizadas).

Errores de código comunes en temas que rompen el editor

Una vez que has confirmado que el tema es el responsable, el siguiente paso es localizar el fragmento de código concreto que está causando el fallo. Existen patrones muy frecuentes que afectan directamente al editor de WordPress.

1. Encolado incorrecto de scripts y estilos

El editor de bloques depende de varios scripts de React y de estilos específicos. Si el tema anula o carga mal los scripts, el editor puede dejar de funcionar. Revisa tu función functions.php y busca llamadas a wp_enqueue_script y wp_dequeue_script.

function mi_tema_scripts() {
    // Ejemplo correcto
    wp_enqueue_style( 'mi-tema-style', get_stylesheet_uri(), [], wp_get_theme()->get( 'Version' ) );
}
add_action( 'wp_enqueue_scripts', 'mi_tema_scripts' );

Evita desregistrar scripts del núcleo como wp-edit-post, wp-blocks o similares, y no cargues versiones personalizadas de librerías como React o jQuery en el admin.

2. Uso indebido de hooks en el área de administración

Algunos temas añaden código que se ejecuta también en el área de administración sin comprobar el contexto. Esto puede romper el editor si se modifican consultas, se fuerzan redirecciones o se cambian capacidades de usuario.

• Evita modificar la query principal en el admin sin condicionales como is_admin() y get_current_screen().
• No fuerces redirecciones globales en hooks como template_redirect que puedan afectar al editor.
• Comprueba que las funciones que cambian roles o capacidades no se ejecutan en cada carga del admin.

3. Errores de PHP en plantillas y functions.php

Un simple error de sintaxis en functions.php o en una plantilla que se carga en el editor puede provocar una pantalla en blanco. Revisa el archivo debug.log y busca errores como Parse error, Fatal error o Call to undefined function.

4. Compatibilidad deficiente con Gutenberg

Algunos temas antiguos no declaran soporte para el editor de bloques o lo hacen de forma incompleta. Esto puede provocar que el editor no cargue ciertas funcionalidades o que se muestre con un diseño roto.

Asegúrate de que tu tema incluye las declaraciones de soporte adecuadas en functions.php:

function mi_tema_soporte_gutenberg() {
    add_theme_support( 'editor-styles' );
    add_theme_support( 'wp-block-styles' );
    add_theme_support( 'align-wide' );
}
add_action( 'after_setup_theme', 'mi_tema_soporte_gutenberg' );

Reparar el tema sin romper el sitio en producción

Una vez identificado el origen del problema, es momento de aplicar la corrección. La clave es hacerlo de forma controlada, minimizando el impacto en el sitio en producción y manteniendo la posibilidad de revertir cambios rápidamente.

1. Crear o usar un entorno de staging

Si tu proveedor de hosting ofrece entornos de staging, clona la web y trabaja allí. Si no, puedes crear una copia manual en un subdominio o en local con herramientas como Local, DevKinsta o similares.

2. Aplicar la corrección en un tema hijo

Siempre que sea posible, evita modificar directamente el tema padre, especialmente si es un tema comercial o se actualiza con frecuencia. Crea un tema hijo y traslada ahí las personalizaciones necesarias para corregir el editor.

• Crea una carpeta de tema hijo con style.css y functions.php mínimos.
• Importa solo las funciones y estilos necesarios para corregir el problema.
• Prueba el editor con el tema hijo activo antes de aplicar cambios en producción.

3. Verificar el editor tras cada cambio

Después de cada modificación en el tema, recarga el editor y revisa tanto el funcionamiento como la consola del navegador. No acumules muchos cambios sin probar; así podrás identificar rápidamente qué línea ha resuelto o provocado un nuevo error.

Buenas prácticas de desarrollo con Gutenberg y editor clásico

Para evitar que el tema vuelva a romper el editor en futuras actualizaciones, conviene seguir una serie de buenas prácticas tanto si trabajas con Gutenberg como si mantienes compatibilidad con el editor clásico o con constructores de páginas externos.

• Usa siempre las funciones nativas de WordPress para encolar scripts y estilos, diferenciando entre frontend y admin.
• No sobreescribas librerías del núcleo (React, jQuery, etc.) en el área de administración.
• Declara el soporte de bloques y estilos del editor de forma explícita en after_setup_theme.
• Evita ejecutar consultas pesadas o modificaciones de la query en el admin sin condicionales.
• Prueba el tema con las últimas versiones de WordPress en un entorno de desarrollo antes de actualizar en producción.

Cuándo cambiar de tema o crear un child theme

No siempre compensa invertir muchas horas en reparar un tema que rompe el editor de forma recurrente. En algunos casos, la mejor decisión a medio plazo es migrar a un tema más moderno y compatible con Gutenberg, o reestructurar el proyecto con un tema hijo bien diseñado.

Señales de que deberías cambiar de tema

• El tema no se actualiza desde hace años y no es compatible con las últimas versiones de WordPress.
• El soporte del desarrollador ha finalizado o no responde a incidencias relacionadas con el editor.
• El código del tema está muy acoplado a un constructor obsoleto o a funciones propias difíciles de mantener.
• Cada actualización de WordPress genera nuevos errores en el editor.

Ventajas de usar un tema hijo bien estructurado

Un tema hijo te permite mantener el tema padre actualizado mientras aplicas personalizaciones específicas sin riesgo de sobrescribir cambios. Esto es especialmente útil para ajustes relacionados con el editor, estilos personalizados y bloques propios.

Herramientas útiles para diagnosticar errores en el editor

Además de los logs de WordPress y del propio panel de administración, existen herramientas que facilitan la detección de errores cuando el tema rompe el editor. Integrarlas en tu flujo de trabajo te ahorrará tiempo y reducirá la probabilidad de introducir fallos críticos.

• Consola del navegador: para ver errores JavaScript, conflictos de scripts y recursos bloqueados por CORS o políticas de seguridad.
• Extensiones de navegador como React Developer Tools, útiles para inspeccionar el árbol de bloques de Gutenberg.
• Plugins de debug como Query Monitor, que muestran errores PHP, hooks ejecutados y scripts encolados.
• Validadores de PHP (PHPCS, PHPStan) para analizar el código del tema según los estándares de WordPress.
• Sistemas de control de versiones (Git) para registrar cambios y revertir rápidamente versiones de archivos del tema.

Checklist rápido para solucionar un editor roto

Cuando el editor de WordPress deja de funcionar y sospechas que el tema es el responsable, puedes seguir este checklist rápido como guía de actuación. Te ayudará a no pasar por alto pasos importantes y a documentar el proceso de reparación.

• Realizar copia de seguridad completa del sitio.
• Activar WP_DEBUG y WP_DEBUG_LOG en wp-config.php.
• Probar el editor con un tema por defecto de WordPress.
• Desactivar todos los plugins y reactivarlos uno a uno.
• Comprobar si el problema aparece solo con el tema hijo o también con el tema padre.
• Revisar functions.php y archivos recientes del tema en busca de errores de sintaxis.
• Verificar el encolado de scripts y estilos, evitando desregistrar scripts del núcleo.
• Probar el editor en un entorno de staging antes de aplicar cambios en producción.
• Documentar la causa del error y la solución aplicada para futuras referencias.

Preguntas frecuentes