Todas as instalações de temas WordPress deviam terminar da mesma forma: clicar em «Ativar», ver um site bonito e ir beber um café. A realidade é mais dura. Em vez do design de demonstração, um ecrã branco, em vez de menus, vazio, e a importação dos dados de demonstração falha com um erro que nunca viu na vida.

Os fóruns do WordPress estão cheios das mesmas perguntas. Os criadores de temas respondem-lhes em círculos há anos. Compilámos os 10 problemas mais comuns de temas WordPress que tanto principiantes como utilizadores experientes encontram, e anexámos uma solução funcional para cada caso. Nada de magia, apenas correções documentadas.

💡 Visão geral rápida:

• Corrigir o erro «stylesheet missing»: estrutura correta do arquivo zip
• Configurar a página inicial para corresponder à demonstração: definições de leitura e modelos
• Remover erros 404 após mudar de tema: redefinir permalinks
• Restaurar menus, imagens destacadas e sliders funcionais: instruções passo a passo
• Guardar edições ao atualizar o tema: temas filho e plugins de CSS

Veja este vídeo para uma análise visual dos problemas típicos de temas e as suas soluções:

1. Stylesheet missing

Descarregou um tema, carrega o ficheiro zip através do painel de administração e recebe uma mensagem seca: «The package could not be installed. The stylesheet is missing.» Primeiro pensamento, o criador enviou uma versão defeituosa.

Na grande maioria dos casos, o problema não é do tema, mas da estrutura do arquivo. Quando descarrega um tema de um marketplace ou do site do criador, dentro do ficheiro zip muitas vezes não está o tema em si, mas uma pasta com documentação, licença, dados de demonstração e o tema propriamente dito num subdiretório. O WordPress espera encontrar o style.css na raiz do arquivo e, em vez disso, encontra uma pasta invólucro.

Como corrigir: descompacte o arquivo no seu computador. Encontre a pasta que contém o style.css, functions.php e index.php, essa é a raiz do tema. Compacte-a num novo zip e carregue através de «Aparência → Temas → Adicionar novo». Se o tema veio sem style.css, acontece, mas raramente, contacte o criador.

2. Erros de importação de dados de demonstração

O tema está instalado e inicia a importação de conteúdo de demonstração via ficheiro XML. O WordPress devolve um erro, a importação é interrompida a meio e os ficheiros multimédia não foram carregados.

Dois cenários típicos aqui.

Cenário 1: erro de importação de artigos. O WordPress tenta criar tipos de conteúdo personalizados (portefólio, testemunhos, equipa) que ainda não estão registados. Solução simples: ative o tema antes de importar, é o tema que regista os tipos de conteúdo personalizados. Se o erro persistir, verifique a documentação: talvez um plugin obrigatório (por exemplo, JetEngine ou ACF) não esteja instalado.

Cenário 2: erro de importação de multimédia. As imagens do conjunto de demonstração não carregam. Marque «Descarregar e importar anexos de ficheiros» antes de iniciar a importação. Se a caixa estiver marcada e os ficheiros ainda assim não carregarem, o servidor do criador está temporariamente indisponível. Contacte o suporte do tema, eles enviarão as imagens como um arquivo separado.

3. A página inicial não corresponde à demonstração

O tema está ativado, os dados importados, mas a página inicial não se parece com o site de demonstração. Onde está a grelha de artigos? Onde está o slider? Onde estão os blocos com ícones?

A razão está quase sempre nas definições de visualização da página inicial e nos modelos.

Opção A: definições de leitura erradas. Vá a «Definições → Leitura». Se o tema usar um modelo de página inicial personalizado, selecione «Uma página estática» e atribua a página necessária como página inicial. Se o tema for construído com base na exibição dos últimos artigos, escolha «Os seus últimos artigos».

Opção B: modelo não selecionado. Abra a página atribuída como página inicial no editor. Na barra lateral «Atributos da Página → Modelo», procure opções com os nomes Home, Front Page, Homepage ou semelhantes. Selecione o modelo, guarde a página e atualize o site.

Se não houver modelos, verifique a documentação do tema. Alguns criadores usam um plugin complementar separado para o layout da página inicial.

4. Endereços URL feios

Uma instalação nova do WordPress produz URLs como yourwebsite.com/?p=1. Para SEO e legibilidade humana, isto é um desastre.

Correção** em 10 segundos:** «Definições → Permalinks» e escolha «Nome do artigo». Isto dá um URL limpo yourwebsite.com/post-name/. Se o site já estiver indexado com URLs antigos, instale um plugin de redireccionamento (por exemplo, Redirection) para evitar perder tráfego. Para sites novos, defina com confiança «Nome do artigo» e guarde, sem necessidade de ações adicionais.

5. Artigos devolvem erro 404

Mudou o tema e algumas páginas foram subitamente para 404. Os artigos estão no lugar, visíveis no admin, mas os links diretos estão vazios.

O problema raiz são os tipos de conteúdo personalizados. Muitos temas registam os seus próprios tipos (portefólio, eventos, produtos). Ao mudar de tema, as regras de reescrita de URL são repostas e o WordPress «esquece-se» de como construir links para estes tipos.

Solução: vá a "Definições → Links permanentes" e clique simplesmente em "Guardar alterações" sem modificar nada. Isto força o WordPress a regenerar a estrutura de URLs. Funciona quase sempre. Se não resultar, verifique as permissões de escrita do ficheiro .htaccess na raiz (o servidor tem de conseguir atualizá-lo).

Leia mais sobre a configuração de links permanentes na documentação do WordPress.

6. Menu vazio após a instalação do tema

Instalou o tema e, no cabeçalho, o vazio. Nem links, nem páginas, embora a demonstração tivesse um menu organizado com itens suspensos.

O tema do WordPress, por defeito, mostra um menu de recurso a partir das páginas criadas. Os temas premium não fazem isto: o programador espera que indique qual o menu e em que área deve ser exibido.

Passo a passo:

• "Aparência → Menus", crie um novo menu (ou edite um existente).
• Adicione páginas, categorias, links personalizados à estrutura do menu.
• No fundo da página, localize o bloco "Localização de exibição", assinale a área do tema pretendida (Menu principal, Navegação principal, Menu do cabeçalho, etc.).
• Guarde o menu.

Mais detalhes: guia de configuração de menus do WordPress.

7. O tema usa imagens destacadas, mas os artigos antigos não as têm

Migrou de um tema antigo que não suportava imagens destacadas (miniaturas de artigos). O novo tema exibe belas grelhas de artigos com imagens, mas centenas dos seus artigos mostram um espaço reservado cinzento em vez de uma pré-visualização.

Definir manualmente imagens destacadas para cada artigo antigo são horas de rotina.

Solução rápida: o plugin Easy Add Thumbnail. Instale, ative e o plugin atribui automaticamente a primeira imagem do conteúdo do artigo como imagem destacada. Se a primeira imagem não se adequar, o plugin permite definir uma imagem padrão. Para artigos novos, crie simplesmente a regra de preencher o bloco "Imagem destacada" antes de publicar.

8. Sliders, acordeões, separadores não funcionam

O tema anuncia sliders, separadores, acordeões e menu móvel, mas nada disto funciona: o slider congelou no primeiro slide, os separadores não alternam, o menu móvel não abre.

O problema é um conflito de JavaScript. Os temas e plugins carregam os seus scripts e, quando duas extensões usam versões diferentes do jQuery ou implementam incorretamente o carregamento, toda a interatividade do frontend se quebra.

Metodologia de procura do culpado:

• Desative todos os plugins de uma só vez.
• Limpe a cache, do servidor, do plugin e do navegador.
• Verifique se os sliders funcionam. Se sim, ative os plugins um a um e atualize o site após cada um.
• O plugin após o qual tudo se estragou é a fonte do conflito.

Encontrado o plugin culpado, procure uma alternativa com funcionalidade semelhante ou contacte os programadores do plugin e do tema, anexando o nome e a versão da parte conflituante.

9. As alterações de CSS não se aplicam

Adicionou CSS personalizado através do personalizador, guardou, atualizou o site e zero reação. As cores, fontes e espaçamentos mantiveram-se como estavam.

O culpado é a cache, muitas vezes com várias camadas: um plugin de cache como o W3 Total Cache comprime e armazena a versão antiga do CSS, o navegador também a mantém e o alojamento adiciona a cache do servidor.

Lista de verificação por camadas:

• Desative o plugin de cache e limpe a sua cache.
• No personalizador, clique em «Guardar» e atualize a página com uma reinicialização forçada da cache do navegador (Ctrl+Shift+R).
• Se o fundo não mudar, o tema pode ter escrito uma imagem de fundo no style.css. Carregue uma imagem de fundo de teste: esta irá sobrepor-se à predefinida.
• Se estiver a editar CSS através de «Aparência → Editor» e receber um erro ao guardar, o problema está nas permissões de acesso aos ficheiros no servidor. Mais detalhes: documentação do WordPress.

10. Atualizou o tema e todas as edições desapareceram

Editou manualmente o style.css, o functions.php ou um modelo de página diretamente nos ficheiros do tema. Chegou uma atualização do tema, clicou em «Atualizar» e todas as alterações foram substituídas pelo código limpo do programador.

Isto não é um erro, mas uma característica da arquitetura do WordPress: as atualizações substituem todos os ficheiros do tema. Nunca edite diretamente os ficheiros de origem do tema.

O que fazer agora: verifique se o seu alojamento tem backups diários. Muitos alojamentos mantêm backups de 30 dias. Se não houver backup e as edições não estiverem documentadas, infelizmente, as alterações estão perdidas.

Como evitar a recorrência:

• Tema filho. Crie um tema filho, que herda tudo do tema principal e permite substituir modelos, estilos e funções sem risco durante as atualizações. Temos um guia completo sobre temas filho do WordPress.

• Plugins de CSS. Para pequenas edições visuais, um plugin é suficiente. O Yellow Pencil fornece um editor visual de estilos em tempo real, e o CSS Hero oferece uma biblioteca de trechos de CSS prontos a usar. Ambos não mexem nos ficheiros do tema e são seguros durante as atualizações.

• Backup. Configure backups regulares do site. Líder entre as soluções gratuitas: UpdraftPlus com agendamento flexível e armazenamento de backups no Dropbox, Google Drive ou S3. Para projetos comerciais, conheça o Solid Backups (anteriormente BackupBuddy) da SolidWP: solução consolidada com backup completo na nuvem e migração conveniente. Os backups por plugin diferem dos backups do servidor de alojamento, pois controla o agendamento e os pontos de restauro por si mesmo.

• Registo de alterações. Registe o que alterou e quando. Um simples Google Doc com datas e descrições das edições poupará horas durante a depuração.

⁉️🤔 Perguntas frequentes

Porque é que o site mostra um ecrã branco depois de instalar um tema?

O Ecrã Branco da Morte é mais frequentemente causado por um erro fatal de PHP: conflito do tema com um plugin ou limite de memória PHP esgotado. Aumente o memory_limit para 256M no php.ini ou através do painel de alojamento. Se não resolver, renomeie a pasta de plugins via FTP para desativar todos de uma vez e ative um a um.

Como descubro qual o plugin que está em conflito com o tema?

Desative todos os plugins. Se o problema desaparecer, ative um a um e verifique o site após cada ativação. O plugin no qual o erro regressar é o que está em conflito. Comunique ao programador do tema o nome e a versão; a maioria dos conflitos resolve-se com a atualização de uma das partes.

É obrigatório criar um tema filho para um par de linhas de CSS?

Não. Para uma pequena quantidade de CSS, utilize «Aparência → Personalizar → CSS adicional» no personalizador. Este bloco não é substituído durante as atualizações do tema. Um tema filho é necessário quando edita modelos PHP, adiciona hooks ou substitui funções.

Posso restaurar edições após uma atualização do tema sem um backup?

Infelizmente, não. A atualização do tema substitui fisicamente os ficheiros no servidor. A versão antiga não fica armazenada em lado nenhum, exceto no seu backup. Portanto, a primeira regra da personalização: tema filho ou plugins de CSS desde o primeiro dia.

Porque é que os URLs dos artigos mudaram depois de instalar o tema?

Alguns temas chamam flush_rewrite_rules() na ativação, o que pode redefinir a estrutura de permalinks. Vá a «Configurações → Permalinks», selecione o seu formato e guarde. Se os URLs já estiverem indexados, instale o plugin Redirection e configure redirecionamentos 301 dos endereços antigos.

O que fazer se o tema se estragou: algoritmo final

Sequência universal de ações para qualquer situação atípica com um tema WordPress:

• Limpar a cache. Plugin de cache, CDN do alojamento, navegador, três camadas. Metade dos temas «avariados» estão apenas a mostrar uma versão em cache.
• Desativar plugins. Todos de uma vez. Funcionou? Procure o culpado reativando um a um.
• Guardar permalinks. Vá às definições e clique em «Guardar»; isto resolve erros 404 e URLs quebradas.
• Verificar a consola do navegador. F12 → Console: as linhas vermelhas indicarão o script que falhou.

Não resolveu? O criador do tema e o Reddit r/WordPress sabem a resposta.