Pular para o conteúdo
15 min de leitura

Arquivo .htaccess: O Guia Prático para Dominar o Apache no seu Site

Compartilhar

Por Equipe Cloudoo ·

Redirecionamentos, URLs amigáveis, proteção de pastas, cache e segurança: o que dá para fazer com o .htaccess e como não quebrar o site.

Neste artigo

Se você já mexeu com hospedagem compartilhada, cPanel ou WordPress, provavelmente esbarrou em um arquivinho discreto chamado .htaccess. Ele quase nunca aparece no gerenciador de arquivos por padrão, mora sozinho na raiz do seu site e, apesar do tamanho modesto, tem poder para forçar HTTPS, criar redirecionamentos, proteger pastas com senha, acelerar o carregamento com cache e até barrar quem tenta roubar suas imagens. É, sem exagero, um dos arquivos mais poderosos que você tem à disposição sem precisar de acesso root ao servidor.

O outro lado dessa moeda é que esse mesmo poder torna o .htaccess perigoso para os desavisados. Uma única linha digitada errado não deixa "meia página" quebrada: ela derruba o site inteiro com um assustador erro 500. Por isso, este guia é dividido em duas frentes. Primeiro, entender o que o arquivo é e como ele funciona por baixo dos panos, para você parar de tratá-lo como magia. Depois, uma coleção prática de receitas testadas — com o código pronto para copiar — junto das precauções que separam quem edita o .htaccess com confiança de quem sua frio toda vez que precisa tocar nele.

O que é o arquivo .htaccess, afinal

O .htaccess (a sigla vem de "hypertext access") é um arquivo de configuração por diretório do servidor web Apache. Traduzindo: em vez de você mexer na configuração global do servidor — algo que numa hospedagem compartilhada você nem tem permissão de fazer —, o Apache permite que você coloque um arquivo de instruções dentro de uma pasta, e essas instruções valem para aquela pasta e todas as subpastas abaixo dela.

É essa característica "por diretório" que faz o .htaccess ser tão útil em hospedagem compartilhada. Você não é o dono do servidor, divide a máquina com dezenas ou centenas de outros sites, mas ainda assim ganha um canal para configurar o comportamento do Apache dentro do seu espaço, sem afetar ninguém. As diretivas que você escreve ali podem controlar redirecionamentos, cabeçalhos HTTP, regras de acesso, tratamento de erros e reescrita de URLs.

Onde o arquivo fica e por que ele é "invisível"

O .htaccess principal costuma ficar na raiz do seu site — normalmente a pasta public_html, www ou htdocs, dependendo da hospedagem. Mas você pode ter vários: um em cada subpasta que precise de regras próprias. As regras de uma pasta se somam às da pasta acima, e regras mais específicas (mais "fundo" na árvore de diretórios) podem sobrescrever as mais genéricas.

Repare que o nome começa com um ponto e não tem extensão nenhuma depois. No mundo Unix/Linux — sistema que roda a esmagadora maioria das hospedagens — arquivos cujo nome começa com ponto são ocultos por convenção. É por isso que ele some da sua vista no FTP ou no gerenciador de arquivos: você precisa ativar a opção "mostrar arquivos ocultos" (no File Manager do cPanel, em "Settings", marque "Show Hidden Files (dotfiles)") para enxergá-lo e editá-lo.

Só o Apache entende .htaccess — e só com AllowOverride ligado

Aqui mora uma confusão comum: o .htaccess não é um padrão universal da web. Ele é uma funcionalidade específica do servidor Apache. Se a sua hospedagem roda outro servidor, o arquivo simplesmente é ignorado.

O caso mais importante é o NGINX, o segundo servidor web mais popular do mundo. O NGINX não usa .htaccess — e isso não é um esquecimento, é uma decisão de arquitetura. Para ganhar desempenho, o NGINX carrega toda a sua configuração uma única vez, quando o serviço inicia, e não fica relendo arquivos de configuração espalhados pelas pastas a cada requisição. As mesmas coisas que você faz no .htaccess (redirecionamentos, reescrita de URL, cache) existem no NGINX, mas ficam nos blocos de configuração do servidor (server {}, location {}), que só o administrador da máquina edita. Ou seja: se você colocar um .htaccess num servidor NGINX, ele será apenas um arquivo de texto morto na pasta.

Mesmo no Apache, o .htaccess só é lido se a diretiva AllowOverride estiver habilitada na configuração global para aquele diretório. Praticamente toda hospedagem compartilhada mantém isso ligado, justamente porque é o que dá autonomia ao cliente. Mas se você administra o próprio servidor (VPS, dedicado) e o .htaccess parece estar sendo ignorado, o primeiro suspeito é um AllowOverride None no arquivo de virtual host.

A regra de ouro: faça backup antes de editar

Antes de qualquer receita, grave isto: sempre faça uma cópia do .htaccess antes de mexer nele. Não é preciosismo. O Apache processa esse arquivo em toda requisição, e se ele encontrar uma diretiva com sintaxe inválida, um módulo que não existe ou uma regra malformada, ele não "pula a linha ruim e segue". Ele responde a cada visitante com um erro 500 (Internal Server Error) e o site inteiro sai do ar — inclusive o painel de administração do WordPress, o que deixa muita gente em pânico achando que foi hackeada.

O procedimento seguro é simples e vale como ritual:

  • Antes de editar, baixe o .htaccess atual ou copie-o para .htaccess.bak na mesma pasta.
  • Faça uma mudança de cada vez e teste o site logo em seguida, em vez de empilhar dez alterações e só depois descobrir que algo quebrou.
  • Se o site cair, restaure o backup imediatamente — renomeie o .bak de volta e o ar volta na hora. Um .htaccess completamente vazio (ou renomeado para .htaccess.off) também derruba as regras e serve para diagnosticar se o problema está mesmo nele.
  • Nunca edite direto no servidor de produção sem ter o backup em mãos, ainda mais numa loja ou site que recebe visitas o tempo todo.

Com essa rede de segurança montada, você pode experimentar as receitas abaixo sem medo.

Casos de uso práticos com código pronto

A seguir estão as tarefas mais comuns que o .htaccess resolve. Copie, cole no seu arquivo, ajuste os domínios e caminhos para os seus, e teste um de cada vez.

Forçar HTTPS (redirecionar http para https)

Depois de instalar um certificado SSL, você quer que todo mundo caia na versão segura do site, mesmo quem digitou o endereço sem o https. Este trecho usa o módulo mod_rewrite para fazer o redirecionamento:

``apache RewriteEngine On RewriteCond %{HTTPS} off RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L] ``

A RewriteCond diz "se a conexão não estiver em HTTPS", e a RewriteRule reenvia o visitante para o mesmo endereço em https. O R=301 marca como redirecionamento permanente (importante para os buscadores) e o L significa "last": pare de processar as próximas regras se esta bater.

Padronizar www ou sem www

Seu site responde tanto em exemplo.com quanto em www.exemplo.com, mas você deve escolher uma versão como oficial para evitar conteúdo duplicado. Para forçar a versão sem www:

``apache RewriteEngine On RewriteCond %{HTTP_HOST} ^www\.exemplo\.com [NC] RewriteRule ^(.*)$ https://exemplo.com/$1 [R=301,L] ``

Se preferir o contrário — forçar o www —, inverta a lógica:

``apache RewriteEngine On RewriteCond %{HTTP_HOST} ^exemplo\.com [NC] RewriteRule ^(.*)$ https://www.exemplo.com/$1 [R=301,L] ``

O [NC] significa "no case", ou seja, não diferencia maiúsculas de minúsculas. Escolha um dos dois blocos, nunca os dois ao mesmo tempo, senão você cria um laço infinito de redirecionamentos.

Redirecionar uma página antiga para uma nova (301)

Reformulou o site e uma URL mudou de endereço? O redirecionamento 301 avisa navegadores e buscadores que a mudança é permanente e transfere a autoridade da página antiga para a nova:

``apache Redirect 301 /pagina-antiga.html https://exemplo.com/pagina-nova/ ``

Repare que aqui usamos a diretiva Redirect, do módulo mod_alias, mais simples que o mod_rewrite e perfeita para redirecionamentos ponto a ponto. O primeiro caminho é relativo (a parte depois do domínio); o segundo é a URL completa de destino.

Páginas de erro personalizadas

Em vez da tela genérica e feia de "404 Not Found" do Apache, você pode servir uma página caprichada, com a identidade do seu site, um menu e uma busca para o visitante não ir embora:

``apache ErrorDocument 404 /erros/nao-encontrado.html ErrorDocument 403 /erros/acesso-negado.html ErrorDocument 500 /erros/erro-servidor.html ``

O caminho aponta para um arquivo dentro do seu site. Uma página 404 bem feita reduz a taxa de rejeição e melhora a experiência de quem clicou num link quebrado.

Proteger uma pasta com senha

O .htaccess consegue trancar uma pasta inteira atrás de uma janela de login do navegador. Ele trabalha em dupla com um segundo arquivo, o .htpasswd, que guarda os usuários e as senhas criptografadas. No .htaccess da pasta que você quer proteger:

``apache AuthType Basic AuthName "Área Restrita" AuthUserFile /home/seu_usuario/.htpasswd Require valid-user ``

O AuthUserFile deve apontar para o caminho absoluto do .htpasswd no servidor — e o ideal é guardá-lo fora da pasta pública, para que ninguém consiga baixá-lo pela web. As senhas dentro do .htpasswd nunca ficam em texto puro; você gera as linhas com uma ferramenta (o próprio cPanel tem o recurso "Directory Privacy", que faz tudo isso na interface, sem você editar arquivo nenhum). É uma camada de proteção simples e válida para ambientes de teste, áreas internas e diretórios que não deveriam ser públicos.

Bloquear acesso a arquivos sensíveis

Alguns arquivos jamais deveriam ser servidos pela web — o wp-config.php do WordPress (que contém a senha do banco de dados), arquivos .env (com chaves e segredos da aplicação), backups e logs. Bloquear o acesso a eles é uma das medidas de segurança mais baratas e eficazes:

```apache <Files "wp-config.php"> Require all denied </Files>

<FilesMatch "^\.env|\.log$|\.bak$"> Require all denied </FilesMatch> ```

O bloco <Files> mira um arquivo específico; o <FilesMatch> usa uma expressão para pegar um conjunto de arquivos de uma vez (aqui, qualquer coisa começando com .env ou terminando em .log e .bak). Ainda que esses arquivos raramente sejam entregues pelo servidor em condições normais, uma configuração errada ou um plugin mal comportado pode expô-los — e essa trava fecha a porta.

Controlar o cache do navegador

Quando um visitante volta ao seu site, o navegador não precisa baixar de novo o logotipo, o CSS e as fontes se você disser a ele por quanto tempo pode guardar esses arquivos. Isso deixa a segunda visita muito mais rápida e alivia o servidor. Com o módulo mod_expires:

``apache <IfModule mod_expires.c> ExpiresActive On ExpiresByType image/jpeg "access plus 1 year" ExpiresByType image/png "access plus 1 year" ExpiresByType text/css "access plus 1 month" ExpiresByType application/javascript "access plus 1 month" </IfModule> ``

O envelope <IfModule mod_expires.c> é uma boa prática defensiva: se o módulo não estiver disponível no servidor, o Apache ignora o bloco em vez de gerar um erro 500. Imagens mudam pouco, então ganham prazos longos; CSS e JS, que você atualiza com mais frequência, recebem prazos mais curtos.

Compactação gzip

Textos — HTML, CSS, JavaScript — comprimem muito bem. Ativar a compactação gzip faz o servidor mandar esses arquivos encolhidos, o navegador descompacta na chegada, e o resultado é uma transferência bem menor e uma página que abre mais rápido. Com o módulo mod_deflate:

``apache <IfModule mod_deflate.c> AddOutputFilterByType DEFLATE text/html text/css text/plain AddOutputFilterByType DEFLATE application/javascript application/json AddOutputFilterByType DEFLATE image/svg+xml </IfModule> ``

Não faz sentido comprimir JPEG, PNG ou vídeos — eles já vêm comprimidos, e tentar de novo só gasta processamento sem reduzir tamanho. Por isso a lista foca em conteúdo baseado em texto.

Bloquear hotlinking de imagens

Hotlinking é quando outro site incorpora as suas imagens usando o endereço direto delas — ou seja, exibe a foto no site dele, mas consumindo a sua banda e o seu servidor a cada carregamento. Você pode barrar isso permitindo que as imagens sejam servidas só quando a requisição vier do seu próprio domínio:

``apache RewriteEngine On RewriteCond %{HTTP_REFERER} !^$ RewriteCond %{HTTP_REFERER} !^https?://(www\.)?exemplo\.com [NC] RewriteRule \.(jpg|jpeg|png|gif|webp)$ - [F] ``

A regra diz: se a imagem estiver sendo requisitada com um referer que não seja o seu site (nem vazio, para não travar acesso direto), responda com [F] (Forbidden). Ajuste exemplo.com para o seu domínio e revise a lista de extensões conforme o seu conteúdo.

URLs amigáveis com mod_rewrite

Este é o coração do mod_rewrite e o motivo de o WordPress pedir um .htaccess funcionando. Em vez de endereços feios como index.php?p=123, você quer URLs limpas e legíveis como exemplo.com/meu-artigo/. Essas URLs amigáveis (os "permalinks" do WordPress) são possíveis porque o mod_rewrite reescreve internamente o endereço bonito para o endereço técnico que a aplicação entende, sem o visitante perceber.

O bloco padrão que o próprio WordPress gera é este:

``apache <IfModule mod_rewrite.c> RewriteEngine On RewriteBase / RewriteRule ^index\.php$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.php [L] </IfModule> ``

Traduzindo a lógica: se o endereço pedido não corresponde a um arquivo real (!-f) nem a uma pasta real (!-d) no servidor, então mande tudo para o index.php, que é quem sabe interpretar o permalink e decidir qual conteúdo mostrar. É por isso que, quando os "links permanentes" do WordPress dão erro 404 depois de uma migração, o conserto quase sempre é recriar esse bloco — em Configurações > Links Permanentes, basta salvar de novo que o WordPress reescreve o .htaccess para você.

Detalhes que fazem diferença

A ordem das regras importa

O Apache lê o .htaccess de cima para baixo, na sequência em que as diretivas aparecem. Isso significa que a ordem não é decorativa: uma regra de redirecionamento colocada antes de outra pode "capturar" a requisição e encerrar o processamento (por causa do flag L) antes que a segunda regra tenha chance de agir.

A recomendação prática é organizar o arquivo em blocos com comentários (linhas iniciadas por #, que o Apache ignora), colocando as regras de reescrita e redirecionamento mais específicas antes das genéricas, e deixando o bloco do WordPress por último. Quando algo redireciona para o lugar errado ou entra em laço, o primeiro lugar para olhar é a ordem em que você empilhou as regras.

Desempenho: por que o vhost é mais rápido no servidor dedicado

Existe um custo escondido no .htaccess: como ele funciona por diretório, o Apache precisa procurar e ler esse arquivo em cada requisição — e não só na pasta final, mas subindo por toda a árvore de diretórios até a raiz, verificando se existe um .htaccess em cada nível. Numa hospedagem compartilhada isso é o preço da autonomia e você aceita, porque não tem alternativa.

Mas se você administra um VPS ou servidor dedicado, tem acesso à configuração dos virtual hosts (o arquivo do vhost). Colocar essas mesmas diretivas diretamente no vhost, com AllowOverride None, faz o Apache carregar as regras uma vez só na inicialização e parar de ficar caçando .htaccess a cada acesso. O ganho de desempenho é real em sites de tráfego alto. A regra prática é: em hospedagem compartilhada, use o .htaccess; quando você controla o servidor, migre as regras para o vhost e desligue a busca por .htaccess onde não precisar dela.

Diagnosticando erros comuns

O erro que mais assusta é o 500 (Internal Server Error) logo após uma edição — e, felizmente, é o mais fácil de resolver: quase sempre é sintaxe inválida, um módulo ausente sem a proteção do <IfModule>, ou uma diretiva mal escrita. Reverta para o backup e o site volta. Depois, reintroduza suas mudanças uma linha por vez até achar a culpada.

Alguns hábitos que economizam dor de cabeça:

  • Olhe o log de erros. No cPanel, procure "Errors" ou "Error Log"; em um servidor próprio, o arquivo costuma ser o error.log do Apache. Ele geralmente aponta o número da linha e o motivo exato da falha, poupando você de adivinhar.
  • Loop de redirecionamento ("a página redirecionou muitas vezes"): revise suas regras de HTTPS e www/sem-www — normalmente há duas regras se contradizendo ou uma condição faltando.
  • Regra que não faz efeito: confirme que o módulo necessário está ativo (mod_rewrite, mod_expires) e que o AllowOverride permite aquele tipo de diretiva. Um .htaccess inteiro ignorado costuma ser AllowOverride None.
  • Cuidado com o cache do navegador nos testes. Redirecionamentos 301 ficam guardados com força pelo navegador; ao testar mudanças, use uma janela anônima ou limpe o cache para não confundir um comportamento antigo com o atual.

Conclusão

O .htaccess é um daqueles arquivos que recompensam quem investe uma tarde entendendo como funcionam. Com poucas linhas você força HTTPS, arruma a versão canônica do domínio, protege arquivos sensíveis, acelera o site com cache e compactação, cria páginas de erro decentes e mantém os permalinks do WordPress no lugar — tudo sem precisar de acesso privilegiado ao servidor.

O segredo para não sofrer é combinar essa coragem com método: entenda que ele só vale no Apache com AllowOverride ligado, que o NGINX joga por outras regras, e que a ordem das diretivas conta. Acima de tudo, transforme o backup em hábito inegociável — copie antes de editar, mude uma coisa por vez, teste, e tenha o log de erros como aliado quando algo der errado. Com essa disciplina, o .htaccess deixa de ser o arquivo misterioso que dá medo e passa a ser uma das ferramentas mais úteis da sua caixa de hospedagem.

Compartilhar

Compartilhar

Leituras relacionadas

Nenhum comentário ainda

Seja o primeiro a comentar.

Deixe seu comentário

Entre com sua conta Canverly para comentar. Você pode usar a mesma conta em qualquer site da rede.

Entrar com Canverly