Hospedagem com 20% de desconto comprando pelo link

Resolvendo problemas

Os problemas comuns num site Velk, da tela branca à mudança que não aparece: o que causa cada um e como descrever um problema para a IA achar rápido.

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_TTL acima 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.
O que a IA confere
# a página responde, e com qual código? $ curl -sI https://example.com/products # a estrutura é válida? falta algum template? $ ./bin/velk schema:validate # por que uma atualização falhou $ cat storage/cache/migration-error.json $ tail storage/logs/migration.log # depois de corrigir a causa $ ./bin/velk migrate # tamanhos de imagem que nunca foram gerados $ ./bin/velk media:variants
No site no ar, a IA roda isso por SSH, a conexão segura com o servidor. Em hospedagem sem SSH, os dois arquivos de uma atualização que falhou dá para ler por FTP (transferência de arquivos).

Como descrever um problema

  1. O sintoma

    O que você vê, com as suas palavras: tela branca, um 404, uma caixa vazia, uma imagem sumida.

  2. Onde

    Qual página, qual idioma, celular ou computador, logado ou não.

  3. O que mudou por último

    Uma atualização, uma publicação do tema, um script novo, uma mudança de hospedagem.

  4. 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.