A maioria dos problemas num site Velk vem de uma lista curta de causas, e a IA sabe onde olhar: o log de erro do servidor, o arquivo .htaccess (as regras de endereço do servidor), a pasta storage/, o tema. A sua parte é a descrição. Abaixo estão os sintomas comuns, o que costuma causar cada um e o que pedir.
Descreva assim
Desde que eu publiquei o tema hoje de manhã, a página Produtos do site da Trigo Bom dá tela branca. A home abre. Olha o log de erro do servidor e me diz a causa antes de mudar qualquer coisa.
Sintoma, onde, o que mudou por último e um pedido de diagnóstico primeiro: isso leva a IA direto ao lugar certo.
Tela branca, ou uma página que só diz “500 Server Error”
Erro de PHP. No site no ar, o APP_DEBUG (a configuração que mostra os detalhes do erro na tela) fica desligado, como deve ser, então o visitante não vê nada útil e o detalhe vai para o log de erro do PHP no servidor. Peça para a IA ler.
Depois de uma atualização, uma causa conhecida é uma função do tema com o mesmo nome de uma que o motor passou a declarar, como a richtext na v3.9.0. As notas de atualização pegam isso quando você atualiza pedindo.
A home abre, as páginas internas dão 404
Quase sempre são as regras de endereço: o .htaccess não subiu, ou o servidor ignora o arquivo. O bin/velk files:init recria um .htaccess que falta a partir do modelo do Velk e nunca sobrescreve um que já existe. No nginx (outro tipo de servidor web), as regras vão na configuração do servidor, a partir do nginx.conf.example do Velk.
Outras duas causas: uma lista como /blog só existe se uma página listar os posts (o Velk não cria listagem automática), e desde a v3.9.0 um template (o arquivo que desenha um tipo de página) declarado no site.json que falta no tema dá 404, e o schema:validate aponta o arquivo em “Warnings:”.
Imagens sumidas
A pasta storage/uploads/ não subiu com o site, ou o servidor não consegue gravar nela. Uma imagem em tamanho cheio onde devia aparecer recortada quer dizer que aquele tamanho nunca foi gerado: o bin/velk media:variants cria os tamanhos que faltam, e o --regen refaz os existentes depois que um tamanho muda no site.json. Se os tamanhos nunca aparecem, pode faltar ao PHP do servidor a extensão de imagens (GD).
Imagens e links quebrados só num site instalado numa subpasta (example.com/novo/) querem dizer que o tema escreve endereços à mão em vez de usar os helpers do Velk (as funções que montam os endereços).
“Atualizando…” ou “Atualização falhou” depois de uma atualização
Quando chegam arquivos novos do motor, o Velk aplica os ajustes do banco (as migrações) na primeira visita. Uma página simples dizendo “Atualizando…” quer dizer que elas estão rodando; ela recarrega sozinha em poucos segundos. “Atualização falhou” quer dizer que uma falhou, e o site fica nessa página até alguém resolver.
O motivo está em storage/cache/migration-error.json e storage/logs/migration.log: peça para a IA ler os dois. Corrigida a causa, o bin/velk migrate aplica o resto e devolve o site. Migração não é tudo ou nada: uma que parou no meio pode precisar antes de um ajuste manual no banco.
Mensagem em branco
Desde a v3.7.1 o motor não escreve as frases que o visitante lê. Ele devolve um código (submitted, validation_failed…) e o tema transforma cada código em palavras, no theme/functions.php. Um código que o tema não conhece aparece como caixa vazia, ou como o código cru: depois de uma atualização que trouxe códigos novos, como os formulários em etapas da v3.7.8, ou numa tela nova, como um login. A correção é uma linha por código; peça para a IA achar os códigos sem frase e escrever o que falta.
E-mail do formulário não chega
O lead fica salvo mesmo quando o e-mail falha, e o envio no painel mostra a situação do e-mail. As causas de sempre: nenhum destinatário na tela do formulário no painel, ou configurações de e-mail (SMTP_*) erradas no .env do servidor (o arquivo com as senhas e chaves do site). Um teste enviado de uma cópia local nunca chega ao cliente, de propósito: a cópia local não recebe os destinatários dos formulários.
A mudança não aparece
- Uma mudança de cor ou de layout. O navegador guarda os arquivos de CSS e JS por um mês, então o tema precisa carregar esses arquivos com uma versão no endereço. A publicação avisa quando falta; peça para a IA acrescentar.
- Conteúdo mudado numa cópia local fica no seu computador: publicar manda só o tema. Mude o conteúdo no site no ar, pelo painel dele ou por conversa.
- Um CDN na frente (uma rede que guarda cópias das páginas perto dos visitantes, como o Cloudflare): com
CACHE_TTLacima de 0, as páginas públicas ficam guardadas por esse tempo. Espere, ou limpe o cache do CDN. - Ainda é rascunho. Salvo não é publicado.
Como descrever um problema
-
O sintoma
O que você vê, com as suas palavras: tela branca, um 404, uma caixa vazia, uma imagem sumida.
-
Onde
Qual página, qual idioma, celular ou computador, logado ou não.
-
O que mudou por último
Uma atualização, uma publicação do tema, um script novo, uma mudança de hospedagem.
-
Diagnóstico primeiro
Peça a causa antes da correção. Para uma correção maior, peça o plano e leia antes de a IA agir.
Perguntas
Posso ligar o APP_DEBUG para ver o erro?
No seu computador, pode. No site no ar, não: ele mostra caminho de arquivo, consulta e versão para qualquer visitante. Deixe a IA ler o log do servidor.
No meu computador funciona, no servidor não. Por quê?
Muitas vezes é a versão do PHP: código que roda num PHP mais novo pode ser erro fatal num mais antigo. Peça para a IA comparar as duas; o PHP do seu computador deve ser o mesmo do servidor.