As configurações do ficheiro wp-config.php que todo o proprietário de um site WordPress deve conhecer

Acabaste de mudar o teu site WordPress para um novo fornecedor de alojamento. Tudo pareceu correr bem durante a transferência.

Então, ao aceder à sua página inicial, depara-se com um erro de ligação à base de dados.

A boa notícia é que, na maioria das vezes, este erro aponta para um ficheiro específico que requer atenção: o wp-config.php.

O ficheiro wp-config.php é o centro de controlo do WordPress. Contém as credenciais da base de dados necessárias para o funcionamento do seu site, além de chaves de segurança, definições de depuração e outras configurações essenciais.

Quando mudar de servidor ou alterar os dados da base de dados, este ficheiro terá de ser atualizado para se adequar ao seu novo ambiente.

Eis o que iremos abordar para que possa trabalhar com confiança neste ficheiro essencial:

• Onde encontrar o ficheiro wp-config.php e as melhores formas de aceder ao mesmo com segurança
• As definições essenciais da base de dados e as configurações de segurança que mantêm o seu site em funcionamento
• Instruções claras para editar o ficheiro através do Gestor de Ficheiros do cPanel ou de clientes FTP
• Alterações específicas da migração que evitam erros de ligação e falhas de funcionalidade
• Estratégias de recuperação quando as edições correm mal e o seu site não carrega

Índice

Sem estas quatro informações (ou se alguma delas estiver incorreta), o WordPress não consegue recuperar as suas publicações, páginas ou definições da base de dados.

O ficheiro contém também as suas chaves de segurança exclusivas, as definições de URL do seu site, as configurações de depuração e os limites de memória.

Os ficheiros do tema, os ficheiros dos plugins e até mesmo os conteúdos que carregou podem estar temporariamente em falta sem que isso prejudique completamente o seu site. Mas e o ficheiro wp-config.php? Se estiver corrompido, em falta ou contiver informações incorretas, todo o seu site exibirá mensagens de erro em vez de conteúdo.

Alguns utilizadores preocupados com a segurança movem o ficheiro wp-config.php um nível acima do diretório raiz do WordPress. Isto coloca as credenciais confidenciais da base de dados fora da estrutura de pastas acessível pela Web. O WordPress é suficientemente inteligente para verificar automaticamente este diretório pai caso não consiga localizar o ficheiro no seu local habitual.

Não consegue encontrar o ficheiro wp-config.php em lado nenhum? Verifique primeiro as definições de visibilidade do seu gestor de ficheiros.

Alguns clientes FTP e painéis de alojamento ocultam, por predefinição, os ficheiros cujos nomes começam com determinados caracteres. Terá de ativar a visualização de ficheiros ocultos nas opções de visualização do seu cliente.

Se o ficheiro realmente não existir, é provável que tenha sido apagado acidentalmente ou que tenha ficado corrompido durante uma transferência. Terá de o restaurar a partir de uma cópia de segurança recente ou recriá-lo manualmente utilizando o modelo wp-config-sample.php que vem incluído em todas as instalações do WordPress.

Configurações essenciais do ficheiro wp-config.php que todo o proprietário de um site deve conhecer

Estas configurações do ficheiro wp-config.php determinam se o seu site WordPress funciona de forma segura — ou se funciona de todo.

Detalhes da ligação à base de dados

As credenciais da sua base de dados são a primeira coisa que o WordPress verifica ao carregar qualquer página.

• DB_NAME indica ao WordPress qual a base de dados que contém o seu conteúdo.
• DB_USER e DB_PASSWORD fornecem as credenciais de acesso.
• DB_HOST indica a localização do seu servidor de base de dados.

Quando se verificam erros de ligação à base de dados, um destes quatro valores está normalmente incorreto.

Chaves de autenticação e salts

As chaves de autenticação e os salts introduzem aleatoriedade na forma como o WordPress encripta as palavras-passe dos utilizadores e as sessões de início de sessão. Quando alguém inicia sessão no seu site, o WordPress utiliza estas cadeias de caracteres para criar cookies únicos e encriptados que verificam a identidade do utilizador.

Sem as chaves adequadas, o seu sistema de início de sessão torna-se suficientemente previsível para que os atacantes o possam explorar através de ataques de força bruta ou de sequestro de sessão.

Prefixo da tabela da base de dados

O WordPress utiliza o prefixo wp_ por predefinição para todos os nomes das tabelas da base de dados. As suas publicações encontram-se em wp_posts, as suas opções em wp_options, e os dados do utilizador em wp_users. Esta nomenclatura padrão torna o WordPress previsível, o que suscita preocupações tanto em termos de conveniência como de segurança.

Alguns proprietários de sites alterar o prefixo da tabela para algo como abc123_ ou mysite_ durante a instalação. O raciocínio é válido: os ataques automatizados visam frequentemente nomes de tabelas padrão do WordPress com tentativas de injeção de SQL. Se as suas tabelas tiverem nomes xyz_posts em vez de wp_posts, os ataques básicos falham imediatamente.

Definições de depuração

WP_DEBUG controla a visibilidade dos erros através de uma simples configuração de tipo verdadeiro/falso no ficheiro wp-config.php.

Defina-o para true, e o WordPress apresenta mensagens de erro diretamente nas páginas do seu site. Verá texto de aviso a vermelho, detalhes de erros fatais e avisos sobre código desatualizado que requer atenção.

No entanto, nunca saia WP_DEBUG modo ativado em sites ativos. Essas mensagens de erro podem revelar informações confidenciais sobre a configuração do seu servidor, os caminhos dos ficheiros e a estrutura da base de dados a qualquer pessoa que visite o seu site durante um erro.

WP_DEBUG_LOG oferece uma alternativa mais segura para ambientes de produção. Esta configuração cria um ficheiro de registo de erros em /wp-content/debug.log em vez de exibir mensagens publicamente. Obtém as informações de diagnóstico de que necessita sem expor detalhes técnicos aos visitantes.

Caminho absoluto

O WordPress precisa de saber exatamente onde está instalado no seu servidor, e é aí que ABSPATH entra em cena. Esta constante define o caminho completo do servidor para a sua instalação do WordPress — não o URL que os visitantes veem, mas a estrutura de pastas real no servidor de alojamento.

Num alojamento partilhado típico, ABSPATH parece que /home/nome_de_utilizador/public_html/ ou /home/nome_de_utilizador/public_html/blog/ se O WordPress está instalado num subdiretório.

Os ambientes de desenvolvimento locais apresentam caminhos como C:\xampp\htdocs\mysite\ no Windows ou /Applications/MAMP/htdocs/mysite/ nos sistemas Mac.

O WordPress utiliza esta informação de caminho absoluto para localizar ficheiros de forma fiável, independentemente da estrutura dos seus URLs ou do diretório a partir do qual o seu site funciona. Quando o WordPress precisa de incluir um ficheiro de tema, carregar um plugin ou aceder a ficheiros multimédia carregados, constrói o caminho completo do ficheiro utilizando ABSPATH como ponto de partida.

Como editar o ficheiro wp-config.php

Deixa-me mostrar-te como editar o ficheiro wp-config.php no teu site.

Faça backup do seu site

Aprendi por experiência própria que é sempre bom fazer uma cópia de segurança do site antes de alterar o ficheiro wp-config.php.

O ficheiro wp-config.php utiliza a sintaxe do PHP, e o PHP não perdoa. Um único ponto e vírgula em falta, uma aspa a mais ou um caractere mal colocado irá gerar um erro fatal que derruba todo o seu site.

Ao contrário de um tema ou plugin com falhas, os erros no ficheiro wp-config.php impedem completamente o carregamento do WordPress.

Se estiver a utilizar um cliente FTP como o FileZilla, clique com o botão direito do rato no ficheiro e selecione «Descarregar».

Os gestores de ficheiros do cPanel funcionam de forma semelhante. Localize o ficheiro wp-config.php, clique com o botão direito do rato e selecione «Descarregar».

Para facilitar a restauração, utilize o Duplicator para criar uma cópia de segurança completa do site. Guarde-a na nuvem para garantir que não fica corrompida.

Se algo correr mal, procure essa cópia de segurança no seu painel de administração e clique em «Restaurar».

Em caso de erros mais graves, volte a carregar o ficheiro de cópia de segurança e o ficheiro de instalação no diretório raiz do seu site. Inicie a restauração através deste URL: https://your-domain/installer.php

O Duplicator irá restaurar o seu site mesmo que este esteja completamente fora de serviço!

Editar o ficheiro wp-config.php através de FTP

O FTP permite-lhe aceder diretamente ao servidor para editar o ficheiro wp-config.php quando o cPanel não está disponível ou se preferir utilizar software de desktop.

Encontre as suas credenciais de FTP no painel de controlo da sua conta de alojamento, normalmente na secção «Contas FTP». Vai precisar do nome do servidor (geralmente o seu nome de domínio ou ftp.seudominio.com), do nome de utilizador e da palavra-passe. Alguns fornecedores de alojamento incluem estes dados no e-mail de boas-vindas.

Abra o seu cliente FTP e introduza estes dados de ligação. Os utilizadores do FileZilla devem introduzir as informações na barra «Quickconnect ». Assim que estiver ligado, verá a estrutura de diretórios do seu servidor no painel direito.

Aceda à pasta principal do seu site, normalmente denominada public_html, www ou o nome do seu domínio.

Clique com o botão direito do rato no ficheiro wp-config.php e selecione «Descarregar» para guardar uma cópia no seu computador. Isto cria tanto a sua cópia de trabalho como uma cópia de segurança, para o caso de algo correr mal durante as edições.

Abra o ficheiro descarregado num editor de texto simples, como o Notepad++ ou o VS Code. Evite o Microsoft Word ou aplicações de texto formatado que adicionam caracteres de formatação invisíveis que prejudicam a sintaxe do PHP.

Faça as alterações com cuidado, verificando se todas as aspas, ponto e vírgulas e parênteses permanecem intactos. Guarde o ficheiro como texto simples, sem qualquer codificação de marca de ordem de bytes (BOM).

Carregue o ficheiro modificado de volta para o seu servidor, substituindo o original. A maioria dos clientes FTP solicita confirmação antes de substituir ficheiros existentes.

Visite o seu site numa nova janela do navegador no prazo de 30 segundos após o carregamento. Se a sua página inicial for apresentada normalmente, significa que as alterações foram bem-sucedidas. Se encontrar erros ou ecrãs em branco, carregue imediatamente a sua cópia de segurança para restaurar a funcionalidade enquanto resolve o problema de sintaxe.

Editar o ficheiro wp-config.php com o cPanel

O Gestor de Ficheiros do cPanel oferece a forma mais simples de editar o ficheiro wp-config.php diretamente no seu servidor. Tudo é feito através da interface web do painel de controlo da sua hospedagem.

Inicie sessão no painel de controlo cPanel da sua conta de alojamento e localize o ícone do Gestor de Ficheiros, que normalmente se encontra na secção «Ficheiros ». Clique nele para abrir o navegador de diretórios do seu servidor numa nova janela ou separador.

Quando o gestor de ficheiros abrir, clique em public_html ou na pasta com o nome do seu domínio para aceder aos ficheiros do seu site.

Se estiver a gerir vários sites, aceda à pasta específica que contém a sua instalação do WordPress.

Vai reconhecer o diretório correto quando vir as pastas wp-admin, wp-content e wp-includes, juntamente com o ficheiro wp-config.php e outros ficheiros essenciais do WordPress.

Clique com o botão direito do rato no ficheiro wp-config.php na lista de ficheiros e selecione «Editar».

O ficheiro abre-se no editor de texto integrado do cPanel, apresentando todas as suas definições de configuração atuais. Efetue as alterações com cuidado, prestando atenção às aspas, aos pontos e vírgulas e à sintaxe correta do PHP.

Guarde as alterações quando terminar a edição. As alterações entram em vigor imediatamente — não é necessário voltar a carregar o ficheiro.

A edição direta no cPanel parece mais rápida porque evita o ciclo de descarregar e carregar. Mas essa conveniência significa que as suas alterações entram em vigor instantaneamente, sem a segurança de testar primeiro localmente.

As mesmas precauções de cópia de segurança e práticas de edição cuidadosas aplicam-se aqui. Um único erro de sintaxe continua a danificar o seu site de forma tão completa como com qualquer outro método de edição.

Como o ficheiro wp-config.php afeta as migrações do WordPress

Já vi migrações perfeitamente planeadas transformarem-se em desastres que se prolongaram por vários dias porque ninguém pensou em verificar as definições de ligação à base de dados até que o site transferido apresentasse erros de ligação.

Eis o que acontece durante uma falha típica de migração: transfere com sucesso todos os seus ficheiros do WordPress para o novo fornecedor de alojamento e importa a sua base de dados. Tudo parece estar concluído. Mas quando acede ao seu site migrado, o WordPress não consegue ligar-se à base de dados porque o seu ficheiro wp-config.php ainda contém as credenciais da base de dados do antigo fornecedor de alojamento.

O seu anterior provedor de alojamento utilizava configurações de base de dados como localhost para DB_HOST e oldhost_dbuser para DB_USER. O seu novo fornecedor de alojamento atribui credenciais completamente diferentes — talvez mysql.newhost.com para o endereço do servidor e newhost_wp123 para o nome de utilizador.

O WordPress não tem como saber desta alteração, a menos que atualize o ficheiro wp-config.php com as informações da base de dados do novo ambiente de alojamento.

As incompatibilidades de URL causam uma série de problemas adicionais, mesmo depois de estabelecer as ligações à base de dados.

Os URLs e os caminhos dos ficheiros do seu site antigo ficam codificados em todo o WordPress de formas que não são imediatamente evidentes. O conteúdo da base de dados, as definições do tema e as configurações dos plugins fazem frequentemente referência a URLs absolutos ou a caminhos do servidor que apontam para a sua configuração de alojamento anterior.

Mesmo com ligações à base de dados corretas, estas referências incompatíveis provocam links quebrados, imagens em falta e problemas de acesso administrativo.

O Duplicator Pro lida com estas atualizações complexas de URLs e caminhos automaticamente durante as migrações. Em vez de ter de procurar manualmente nos registos da base de dados e nos ficheiros de configuração para encontrar referências codificadas, o processo de migração do Duplicator Pro atualiza URLs, caminhos e definições do ficheiro wp-config.php numa única operação coordenada.

Formas comuns de editar o ficheiro wp-config.php

A maioria dos proprietários de sites descobre a edição do ficheiro wp-config.php por necessidade — para corrigir erros de ligação à base de dados ou resolver problemas com migrações que falharam. Mas, assim que se familiarizar com a estrutura do ficheiro, várias melhorias práticas tornam-se acessíveis para depurar problemas, reforçar a segurança e otimizar o desempenho.

Depuração

Cenário define('WP_SCRIPT_DEBUG', true); transforma a depuração de um processo de adivinhação numa resolução de problemas direcionada. Em vez de referências enigmáticas, as mensagens de erro apontam para nomes de funções legíveis e números de linha lógicos num código devidamente formatado.

WP_DEBUG_DISPLAY determina se as mensagens de erro aparecem diretamente nas páginas do seu site ou se permanecem ocultas aos visitantes. Quando definido como false, os erros continuam a ser gerados e registados, mas não aparecerão como avisos em vermelho que perturbam o design do seu site.

Combino estas configurações estrategicamente, dependendo do ambiente. Nos sites de desenvolvimento, ativo ambas as opções WP_DEBUG e WP_DEBUG_DISPLAY para detectar os problemas imediatamente.

Nos servidores de teste, utilizo WP_DEBUG com WP_DEBUG_LOG mas desativar WP_DEBUG_DISPLAY para detetar problemas sem comprometer a experiência de teste visual.

Nunca deixe a depuração ativada em sites em produção. Essas mensagens de erro revelam informações confidenciais sobre a configuração do servidor, os caminhos dos ficheiros, as versões dos plugins e a estrutura da base de dados.

Melhorias de segurança

O WordPress utiliza proteções contra a edição de ficheiros para impedir alterações não autorizadas através da interface de administração. Se a sua conta de alojamento for comprometida ou se alguém que não deva ter acesso de administrador o obtiver, estas constantes criam barreiras contra os ataques mais prejudiciais.

DISALLOW_FILE_EDIT remove completamente as páginas do editor de temas e plugins do painel de controlo do WordPress. Sem esta proteção, qualquer pessoa com acesso de administrador pode inserir código PHP malicioso diretamente através de Aparência » Editor de temas ou Plugins » Editor de plugins.

DISALLOW_FILE_MODS leva a proteção um passo mais além, impedindo todas as alterações de ficheiros através da interface de administração do WordPress. Isto inclui a instalação de plugins, o carregamento de temas, Atualizações do núcleo do WordPresse atualizações automáticas em segundo plano.

A desvantagem é significativa: perde-se a conveniência da instalação de plugins com um único clique e das atualizações de segurança automáticas. Cada alteração requer acesso manual ao sistema de ficheiros, o que torna esta opção prática apenas quando se dispõe de processos de desenvolvimento fiáveis.

FORCE_SSL_ADMIN requer ligações HTTPS encriptadas para todas as atividades administrativas do WordPress. As páginas de início de sessão, o acesso ao painel de controlo e as funções administrativas não funcionam através de ligações HTTP não encriptadas.

Conjunto define('FORCE_SSL_ADMIN', true); quando o seu site trata de informações confidenciais ou opera sob requisitos de conformidade que exigem acesso administrativo encriptado.

Esta funcionalidade funciona independentemente da configuração geral de SSL do seu site — pode ativar a encriptação para a área de administração, permitindo ao mesmo tempo o uso de HTTP nas páginas públicas.

Melhorias no desempenho

Os sites com elevado tráfego e atualizações frequentes de conteúdo enfrentam um problema de desempenho oculto: o inchaço da base de dados devido a revisões ilimitadas das publicações. Por predefinição, o WordPress guarda todos os rascunhos, gravações automáticas e versões publicadas do seu conteúdo.

WP_POST_REVISIONS determina quantas versões o WordPress mantém para cada publicação ou página. Configuração define('WP_POST_REVISIONS', 3); limita o armazenamento à sua versão atual e às três revisões anteriores.

Isso costuma ser suficiente para recuperar conteúdos apagados acidentalmente ou reverter edições problemáticas, sem a sobrecarga que um histórico ilimitado representaria para a base de dados.

O painel de controlo do WordPress consome mais memória do que as suas páginas públicas, especialmente durante a instalação de plugins, a personalização de temas ou operações em massa com conteúdos. WP_MAX_MEMORY_LIMIT especificamente controla a disponibilidade de memória para tarefas administrativas.

Adicionar define('WP_MAX_MEMORY_LIMIT', '512M'); proporciona margem de manobra para operações que exigem muita memória, como a importação de ficheiros XML de grande dimensão, o processamento em lote de imagens ou a gestão de configurações complexas de plugins.

O WordPress mantém o conteúdo eliminado na lixeira durante 30 dias antes de o remover definitivamente. Configuração define('EMPTY_TRASH_DAYS', 7); reduz o período de retenção para uma semana, eliminar automaticamente o conteúdo eliminado de forma mais agressiva.

Os sites de notícias ou fóruns muito movimentados beneficiam de períodos de retenção mais curtos, uma vez que o conteúdo eliminado raramente precisa de ser recuperado após alguns dias.

Problemas comuns no ficheiro wp-config.php e como resolvê-los

A maioria dos problemas com o ficheiro wp-config.php segue padrões previsíveis. Quando se sabe o que procurar, esses erros passam a ser ferramentas de diagnóstico, em vez de problemas misteriosos.

Ecrã branco da morte

O seu site apresenta uma página em branco em vez do conteúdo. Normalmente, isto significa que o PHP não consegue analisar o seu ficheiro wp-config.php devido a problemas de sintaxe.

A falta de ponto e vírgula é a principal causa disto. Todas as linhas no ficheiro wp-config.php que começam com define tem de terminar com um ponto e vírgula. Se apagar um por engano, o PHP deixa de processar todo o ficheiro.

O mesmo acontece com aspas incompatíveis — abrir uma cadeia de caracteres com uma aspa simples, mas fechá-la com uma aspa dupla, interrompe completamente a análise do PHP.

Já vi proprietários de sites a passar horas a tentar resolver problemas com base em teorias complexas, quando o verdadeiro problema era um erro de digitação 'DB_NAME', 'database_name"); em vez de 'DB_NAME', 'database_name');. Essa aspa a mais estraga todo o site.

A solução é simples, se tiver guardado esse ficheiro de cópia de segurança: carregue o seu ficheiro wp-config.php original para restaurar a funcionalidade imediatamente e, em seguida, volte a tentar fazer as suas edições com mais cuidado.

Erro ao estabelecer uma ligação à base de dados

A boa notícia é que o WordPress em si funciona bem — só não consegue aceder à sua base de dados.

Verifique primeiro as quatro constantes da base de dados: DB_NAME, DB_USER, DB_PASSWORDe DB_HOST. Uma destas opções não corresponde às configurações reais da base de dados do seu fornecedor de alojamento.

Problemas de permissões e codificação

Por vezes, o ficheiro wp-config.php contém as informações corretas, mas o WordPress continua sem conseguir lê-lo. As permissões do ficheiro podem ser demasiado restritivas (o WordPress necessita, no mínimo, de permissões 644 para ler o ficheiro), ou a codificação do ficheiro contém caracteres ocultos que impedem a análise do PHP.

Isto acontece quando se edita o ficheiro wp-config.php no Microsoft Word ou noutros programas de texto formatado que inserem códigos de formatação invisíveis. Utilize sempre editores de texto simples, como o Notepad++ ou o VS Code, para alterar o ficheiro wp-config.php.

A propriedade incorreta dos ficheiros também impede o WordPress de ler o ficheiro wp-config.php, mesmo com as permissões corretas. O seu fornecedor de alojamento pode resolver problemas de propriedade, mas estes nem sempre são evidentes até se começar a resolver problemas de acesso.

Como restaurar o ficheiro wp-config.php

Quando as alterações no ficheiro wp-config.php danificam o seu site, restaurar uma cópia de segurança é sempre melhor do que tentar resolver o problema.

Se tiver uma cópia de segurança recente do Duplicator, feita antes das alterações, terá todas as funcionalidades restauradas em menos de cinco minutos. Basta clicar em «Restaurar».

Isto reverte instantaneamente as alterações no seu site, evitando horas de depuração de erros de sintaxe ou problemas de ligação à base de dados.

Quando não for possível restaurar a cópia de segurança, pode recriar o ficheiro wp-config.php a partir do zero, utilizando o modelo de exemplo do WordPress. Descarregue o ficheiro wp-config-sample.php de uma instalação nova do WordPress e renomeie-o para wp-config.php.

O ficheiro de exemplo contém toda a estrutura básica de que necessita. Substitua as credenciais de base de dados provisórias pelos valores reais, que pode encontrar na secção de base de dados do painel de controlo do seu alojamento.

Perguntas mais frequentes (FAQs)

Assuma o controlo da configuração do seu WordPress

O wp-config.php é um ficheiro poderoso, mas previsível. Os erros de ligação à base de dados, as melhorias de segurança e as otimizações de desempenho seguem todos padrões lógicos, assim que se compreende a estrutura e a finalidade do ficheiro.

Eis uma dica extra: crie um ficheiro de documentação que liste as suas definições personalizadas no wp-config.php e a sua finalidade. Quando precisar de recriar o ficheiro ou de migrar para um novo servidor, terá uma referência para as suas escolhas de configuração específicas, em vez de ter de tentar lembrar-se do que cada definição personalizada fazia.

Pronto para assumir o controlo total das suas migrações e cópias de segurança do WordPress? O Duplicator Pro cria cópias de segurança completas do site, incluindo as configurações do ficheiro wp-config.php, tornando as transferências de sites e os cenários de recuperação simples e sem complicações.

Já que está aqui, acho que vai gostar destes guias WordPress relacionados:

• Precisa de um site de teste?
• API REST do WordPress para iniciantes: Aceder ao seu conteúdo em qualquer lugar
• Como editar o seu ficheiro Hosts antes das migrações para o WordPress (Tutorial para Windows, Mac e Linux)
• Como importar ficheiros no WordPress
• Como desfazer alterações no WordPress (5 métodos)
• Como restaurar um site WordPress para uma data anterior sem um backup