Hosting con 20% de descuento comprando por el enlace

Solución de problemas

Los problemas habituales en un sitio Velk, de la pantalla en blanco al cambio que no aparece: qué causa cada uno y cómo describir un problema para que la IA lo encuentre rápido.

La mayoría de los problemas en un sitio Velk vienen de una lista corta de causas, y la IA sabe dónde mirar: el registro de errores del servidor, el archivo .htaccess (las reglas de direcciones del servidor), la carpeta storage/, el tema. Tu parte es la descripción. Abajo están los síntomas habituales, qué suele causar cada uno y qué pedir.

Descríbelo así

Desde que publiqué el tema esta mañana, la página Productos del sitio de Trigo Bom muestra una pantalla en blanco. La página de inicio abre. Lee el registro de errores del servidor y dime la causa antes de cambiar nada.

Síntoma, dónde, qué cambió por último y un pedido de diagnóstico primero: eso lleva a la IA directo al lugar correcto.

Pantalla en blanco, o una página que solo dice “500 Server Error”

Un error de PHP. En un sitio en línea, APP_DEBUG (la configuración que muestra los detalles del error en pantalla) está apagado, como debe ser, así que el visitante no ve nada útil y el detalle va al registro de errores de PHP del servidor. Pídele a la IA que lo lea.

Después de una actualización, una causa conocida es una función del tema con el mismo nombre que una que el motor ahora declara, como richtext en la v3.9.0. Las notas de actualización lo detectan cuando actualizas pidiéndolo.

La página de inicio abre, las páginas internas dan 404

Casi siempre son las reglas de direcciones: el .htaccess no se subió, o el servidor lo ignora. bin/velk files:init vuelve a crear un .htaccess que falta a partir de la plantilla de Velk y nunca sobrescribe uno que ya existe. En nginx (otro tipo de servidor web), las reglas van en la configuración del servidor, a partir del nginx.conf.example de Velk.

Otras dos causas: una lista como /blog solo existe si una página lista las entradas (Velk no crea listados automáticos), y desde la v3.9.0 una plantilla (el archivo que dibuja un tipo de página) declarada en site.json que falta en el tema da 404, y schema:validate la nombra en “Warnings:”.

Imágenes que faltan

La carpeta storage/uploads/ no se subió con el sitio, o el servidor no puede escribir en ella. Una imagen en tamaño completo donde debía verse recortada significa que ese tamaño nunca se generó: bin/velk media:variants crea los tamaños que faltan, y --regen rehace los existentes después de cambiar un tamaño en site.json. Si los tamaños nunca aparecen, al PHP del servidor puede faltarle la extensión de imágenes (GD).

Imágenes y enlaces rotos solo en un sitio instalado en una subcarpeta (example.com/nuevo/) significan que el tema escribe direcciones a mano en lugar de usar los helpers de Velk (las funciones que arman las direcciones).

“Atualizando…” o “Atualização falhou” después de una actualización

Cuando llegan archivos nuevos del motor, Velk aplica los ajustes de la base de datos (las migraciones) en la primera visita. Una página simple que dice “Atualizando…” (“Actualizando…”, en portugués) significa que están corriendo; se recarga sola en pocos segundos. “Atualização falhou” (“La actualización falló”) significa que una falló, y el sitio se queda en esa página hasta que se resuelva.

El motivo está en storage/cache/migration-error.json y storage/logs/migration.log: pídele a la IA que lea los dos. Una vez corregida la causa, bin/velk migrate aplica lo que falta y devuelve el sitio. Las migraciones no son todo o nada: una que se detuvo a la mitad puede necesitar antes un ajuste manual en la base de datos.

Un mensaje en blanco

Desde la v3.7.1 el motor no escribe las frases que lee el visitante. Devuelve un código (submitted, validation_failed…) y el tema convierte cada código en palabras, en theme/functions.php. Un código que el tema no conoce aparece como una caja vacía, o como el código tal cual: después de una actualización que trajo códigos nuevos, como los formularios por pasos de la v3.7.8, o en una pantalla nueva, como un inicio de sesión. La solución es una línea por código; pídele a la IA que encuentre los códigos sin frase y que escriba lo que falta.

Los correos del formulario no llegan

El lead queda guardado aunque el correo falle, y el envío en el panel muestra el estado del correo. Las causas habituales: ningún destinatario en la pantalla del formulario en el panel, o una configuración de correo (SMTP_*) incorrecta en el .env del servidor (el archivo con las contraseñas y claves del sitio). Una prueba enviada desde una copia local nunca le llega al cliente, a propósito: la copia local no recibe los destinatarios de los formularios.

Un cambio no aparece

  • Un cambio de color o de diseño. Los navegadores guardan los archivos CSS y JS durante un mes, así que el tema tiene que cargarlos con una versión en la dirección. La publicación avisa cuando falta; pídele a la IA que la agregue.
  • Contenido cambiado en una copia local se queda en tu computadora: publicar envía solo el tema. Cambia el contenido en el sitio en línea, en su panel o por conversación.
  • Un CDN delante (una red que guarda copias de las páginas cerca de los visitantes, como Cloudflare): con CACHE_TTL mayor que 0, las páginas públicas quedan guardadas ese tiempo. Espera, o limpia la caché del CDN.
  • Todavía es un borrador. Guardado no es publicado.
Lo que revisa la IA
# ¿la página responde, y con qué código? $ curl -sI https://example.com/products # ¿la estructura es válida? ¿falta una plantilla? $ ./bin/velk schema:validate # por qué falló una actualización $ cat storage/cache/migration-error.json $ tail storage/logs/migration.log # una vez corregida la causa $ ./bin/velk migrate # tamaños de imagen que nunca se generaron $ ./bin/velk media:variants
En un sitio en línea, la IA ejecuta esto por SSH, la conexión segura con el servidor. En un hosting sin SSH, los dos archivos de una actualización fallida se pueden leer por FTP (transferencia de archivos).

Cómo describir un problema

  1. El síntoma

    Lo que ves, con tus palabras: una pantalla en blanco, un 404, una caja vacía, una imagen que falta.

  2. Dónde

    Qué página, qué idioma, teléfono o computadora, con sesión iniciada o no.

  3. Qué cambió por último

    Una actualización, una publicación del tema, un script nuevo, una mudanza de hosting.

  4. Primero el diagnóstico

    Pide la causa antes de la solución. Para una solución grande, pide el plan y léelo antes de que la IA actúe.

Preguntas

¿Puedo activar APP_DEBUG para ver el error?

En tu computadora, sí. En el sitio en línea, no: muestra rutas de archivos, consultas y versiones a cualquier visitante. Deja que la IA lea el registro del servidor.

En mi computadora funciona y en el servidor no. ¿Por qué?

Muchas veces es la versión de PHP: código que corre en un PHP más nuevo puede ser un error fatal en uno más antiguo. Pídele a la IA que compare las dos; el PHP de tu computadora debería ser el mismo que el del servidor.