Vazcell

Config Split en Drupal: configuración distinta por entorno, con ejemplos

Por Adrián Vázquez · Actualizado el · 11 min de lectura

Este artículo se publicó en el blog anterior de Vazcell y lo he revisado y actualizado para Drupal 10 y 11.

En resumen

Config Split permite que parte de la configuración de Drupal solo exista o cambie en un entorno concreto: módulos de desarrollo solo en local, la caché de CSS y JS desactivada en local o un servidor de correo distinto en producción. Se crea un split por entorno, se elige qué va en cada uno, se activa con una línea en settings.php y a partir de ahí drush cex y drush cim lo tienen en cuenta solos.

Para qué sirve Config Split

La sincronización de configuración de Drupal exporta toda la configuración del sitio a archivos YML, pero por defecto es la misma en todos los entornos. Config Split añade el concepto de entorno: puedes tener módulos que solo se activan en local, o ajustes que cambian entre desarrollo y producción, sin tocar la configuración común.

  • Módulos de desarrollo (Devel, Webprofiler, Stage File Proxy) activos en local y nunca en producción.
  • Agregación de CSS y JS y caché de páginas desactivadas en local y activadas en producción.
  • Servidor de correo: un capturador como Mailpit en local y el SMTP real en producción.
  • Indexación de búsqueda, integraciones o tareas programadas que solo deben ejecutarse en producción.

Instalación

composer require drupal/config_split
drush en config_split

Para Drupal 10 y 11 se usa la versión 2 del módulo. Después, en Configuración → Desarrollo → Sincronización de configuración verás la pestaña de Configuration Split, con la lista de splits (al principio, vacía).

Estructura de carpetas recomendada

Lo más claro es guardar cada split en su propia carpeta, junto a la configuración común y fuera del directorio público:

proyecto/
├── config/
│   ├── sync/      ← configuración común (config_sync_directory)
│   ├── local/     ← split "local"
│   └── prod/      ← split "prod"
└── web/           ← raíz pública de Drupal

Al crear el split indicas la carpeta relativa a la raíz de Drupal, por ejemplo ../config/local. Tiene que existir y tener permisos de escritura.

Complete split y partial split

  • Complete split: lo que elijas aquí desaparece de la configuración común (config/sync) y solo existe en el split. Si eliges un módulo, también se lleva su configuración. Es ideal para módulos de desarrollo como Devel, que nunca deberían activarse en producción.
  • Partial split (en la versión 1 se llamaba conditional split): la configuración común se mantiene y en el split solo se guarda la diferencia. Es lo que más uso, porque el sitio se puede desplegar sin depender de que haya un split activo.
Qué tipo de split usar en cada caso
CasoTipoPor qué
Devel o Webprofiler solo en localComplete split (módulo)No debe existir nada de ellos en producción
Agregación de CSS/JS desactivada en localPartial split (system.performance)La configuración común sigue siendo la de producción
SMTP distinto en local y producciónPartial splitSolo cambian unos pocos valores
Módulo de monitorización solo en producciónComplete split en el split prodEn local no hace falta ni activarlo

Ejemplo completo: split local y split prod

  1. Crea las carpetas config/local y config/prod.
  2. Crea el split local: nombre local, carpeta ../config/local, en Complete split marca los módulos Devel y Stage File Proxy y en Partial split añade system.performance.
  3. Crea el split prod: nombre prod, carpeta ../config/prod y los módulos o ajustes que solo deban existir en producción.
  4. Deja los dos splits desactivados en la interfaz: se activan desde settings.php, como se ve en el siguiente apartado.
  5. Activa el split local en tu entorno, limpia la caché con drush cr y ajusta lo que quieras distinto en local (por ejemplo, desactiva la agregación de CSS y JS).
  6. Exporta con drush cex: lo común va a config/sync y lo del split local a config/local.

En el repositorio, el YML del split (config/sync/config_split.config_split.local.yml) se guarda con status: false. Quien lo activa es cada entorno con su settings.php, así nunca se cuela un split activo en producción por un export hecho en local.

Activar el split en cada entorno

Cada entorno activa su split desde settings.php (o desde un settings.local.php que no se suba al repositorio):

// settings.local.php (solo en tu máquina)
$config['config_split.config_split.local']['status'] = TRUE;
$config['config_split.config_split.prod']['status'] = FALSE;

Es más cómodo y más seguro decidirlo con una variable de entorno del servidor, así el mismo settings.php sirve para todos:

// settings.php
$env = getenv('APP_ENV') ?: 'prod';

$config['config_split.config_split.local']['status'] = $env === 'local';
$config['config_split.config_split.prod']['status'] = $env === 'prod';

Comandos de Drush

Con la versión 2 no hacen falta comandos especiales en el día a día: drush cex y drush cim ya tienen en cuenta qué splits están activos.

# Exportar: lo común a config/sync y lo de los splits activos a su carpeta
drush cex -y

# Importar: configuración común + splits activos en este entorno
drush cim -y

# Ver qué cambiaría antes de importar
drush config:status

Después de cambiar settings.php ejecuta siempre drush cr: hasta que no se limpia la caché, Drupal puede seguir viendo el split con su estado anterior.

Flujo de despliegue

  1. En local, con el split local activo, haces los cambios y exportas con drush cex.
  2. Subes al repositorio config/sync, config/local y config/prod.
  3. En el servidor, tras el despliegue: composer install, drush updb -y, drush cim -y y drush cr.
  4. Como en producción solo está activo el split prod, Devel y los ajustes de local no se importan nunca.

Errores típicos y cómo resolverlos

  • El split no exporta nada: suele ser que no está activo en ese entorno o que falta un drush cr después de tocar settings.php. Compruébalo en la pestaña de Configuration Split.
  • La carpeta del split no existe o no tiene permisos de escritura: créala y revisa los permisos del usuario que ejecuta Drush.
  • Devel aparece en core.extension de config/sync: lo exportaste sin el split local activo. Activa el split, limpia caché y vuelve a exportar.
  • Tras drush cim en producción desaparece un módulo: ese módulo estaba en un complete split que no está activo en producción. Sácalo del split si debe estar en todos los entornos.
  • Los cambios de un partial split se pierden: se hicieron con el split desactivado y acabaron en config/sync. Activa el split antes de cambiar y exportar ese ajuste.

Preguntas frecuentes

¿Qué diferencia hay entre Config Split y Config Ignore?

Config Split separa configuración por entornos. Config Ignore hace que Drupal no sobrescriba cierta configuración al importar, útil para ajustes que cambia el cliente en producción. Se usan a menudo juntos.

¿Config Split funciona en Drupal 10 y 11?

Sí, con la versión 2 del módulo. Si vienes de la versión 1, revisa las notas de actualización en drupal.org, porque cambian algunas opciones y el conditional split pasa a llamarse partial split.

¿Qué diferencia hay entre complete split y partial split?

Complete split saca la configuración de config/sync y la deja solo en el split. Partial split mantiene la configuración común y guarda en el split solo lo que cambia en ese entorno.

¿Puedo tener más de un split activo a la vez?

Sí. Por ejemplo, un split compartido por desarrollo y staging y otro solo para local. Si dos splits tocan la misma configuración, se aplican en el orden del campo weight.

¿Prefieres que te lo mire yo?

Cuéntame tu caso y te digo qué haría, cuánto costaría y cuánto tardaríamos, sin compromiso.

Pedir presupuesto gratis