Las imágenes son la parte del sitio que más fácilmente “se vuelve más lenta con el uso”: originales de varios MB, una página de listado que carga más de diez imágenes a la vez, miniaturas rotas, cargas rechazadas por el servidor. X1 reúne estos problemas en dos páginas de configuración: método de almacenamiento y procesamiento de imágenes. Primero entendamos estas dos partes y luego hablemos de la CDN.

Ejemplo de página de inicio del frontend de KingCMS X1
La velocidad de carga de las imágenes del frontend depende de tres ajustes: ubicación de guardado, tamaño y formato.

1. Dónde se almacenan las imágenes

La sección «Configuración → Contenido y medios → Almacenamiento» del panel de administración (/admin/settings/content/storage) determina la ubicación de guardado; por defecto es «Local»: las imágenes se escriben en data/uploads/年/月/ fuera de la raíz del sitio, y el frontend accede a ellas mediante /media/年/月/.... nginx debe apuntar /media/ a data/uploads/ y desactivar la ejecución de PHP en ese directorio; de lo contrario, las imágenes se ejecutarán como programas.

Las listas y las miniaturas usan /img/...; en el primer acceso el programa genera WebP y lo guarda en public/img/; después el servidor web lo sirve directamente. Este directorio debe tener permisos de escritura; de lo contrario, las miniaturas devolverán 404. Si se elige almacenamiento local, también se puede indicar un prefijo de CDN (por ejemplo, https://cdn.example.com); la ruta firmada no cambia y es adecuada para caché a largo plazo.

La otra opción es Cloudflare Images: el ID de cuenta, el Hash de cuenta y la clave de API deben tener valor; de lo contrario, no se puede guardar. Tras guardar, el token no se vuelve a mostrar; si se envía vacío, se conserva el valor original. Las imágenes recién subidas se guardan en Cloudflare, y el registro de medios conserva el ID de la imagen y la dirección pública.

2. Tamaños y formatos

«Configuración → Contenido y medios → Procesamiento de imágenes» (/admin/settings/content/image) controla el escalado y el formato de guardado; los valores predeterminados son:

  • Ancho máximo y alto máximo: 1024 píxeles cada uno; 0 significa sin límite;
  • Formato de salida: WebP; opcionalmente JPEG, PNG;
  • Calidad de compresión: 92 (1–100; la compresión PNG es sin pérdida y omite este ajuste);
  • Límite por archivo: 20 MB.

La regla de escalado evalúa el ancho y el alto por separado y reduce proporcionalmente según la proporción menor, sin recortar ni ampliar. Por ejemplo, si la imagen original es de 2048×1536 y el ancho y alto máximos son 1024, el resultado es 1024×768. Si la imagen original tiene canal alfa y se elige JPEG como formato de salida, el programa cambia automáticamente a PNG para evitar que las zonas transparentes se vuelvan negras.

Ejemplo de página de detalles de producto de KingCMS X1
Las imágenes de producto y las miniaturas de listado se generan con el mismo conjunto de reglas de tamaño; los cambios de configuración se aplican a las imágenes nuevas.

3. Límites de carga

Se admiten tres formatos: JPG, PNG y WebP; la extensión del archivo debe coincidir con el contenido real; de lo contrario, se rechaza; una sola imagen no puede superar los 40 millones de píxeles. El «límite por archivo» es una restricción de la capa del programa; upload_max_filesize, post_max_size de PHP y client_max_body_size de nginx deben ser mayores o iguales que ese límite; de lo contrario, la solicitud será rechazada por el servidor antes de llegar al programa.

Las imágenes con el mismo contenido reutilizan el registro de medios existente y no ocupan espacio adicional; subir repetidamente la misma imagen no aumenta el uso de disco.

4. Preguntas frecuentes

  1. Miniaturas rotas: con almacenamiento local, comprobar si public/img/ tiene permisos de escritura; con Cloudflare, comprobar si están activadas las flexible variants; de lo contrario, la salida por tamaño fallará.
  2. Carga rechazada: primero comprobar que la extensión coincida con el contenido, luego si los píxeles superan los 40 millones y si el archivo supera el límite, y por último si los límites de PHP/nginx son menores que la configuración del programa.
  3. Imagen transparente que se vuelve negra: se eligió JPEG como formato de salida; cambiar a WebP o PNG.
  4. La dirección de la imagen lleva el prefijo de CDN pero no abre: el prefijo solo se aplica al almacenamiento local; confirmar que la CDN apunta al origen del sitio.

Resumen

La configuración de imágenes se reduce a tres cosas: dónde se guardan, a qué tamaño se reducen y en qué formato se guardan. Con almacenamiento local, primero hay que configurar bien /media/ y public/img/; si se va a usar Cloudflare Images, hay que configurar de una vez las tres credenciales y las flexible variants. El resto se deja a los valores predeterminados 1024/WebP/92, suficientes para la mayoría de los sitios.