O que é um Arquivo .htaccess? (Guia de 5 Minutos)

O arquivo .htaccess é uma das ferramentas mais poderosas para quem trabalha com sites em servidores Apache. Se você está começando agora, provavelmente já ouviu falar dele mas não sabe exatamente para que serve.

A ideia deste guia é descomplicar o .htaccess de uma vez por todas. Você vai entender o que ele faz, onde fica, como criar e – principalmente – como usar sem medo de quebrar seu site.

E olha, .htaccess não é bicho de sete cabeças. Com alguns cuidados básicos, você consegue controlar redirecionamentos, melhorar a segurança e criar URLs mais limpas. Tudo isso sem precisar mexer nas configurações principais do servidor.

O que é um Arquivo .htaccess, Exatamente?

O .htaccess (sigla para "hypertext access") é um arquivo de texto simples que contém instruções para o servidor Apache. Ele funciona no nível de pastas – você coloca um arquivo desses numa pasta do seu site, e ele aplica regras específicas para aquela pasta e todas as subpastas dentro dela.

A grande sacada do .htaccess é que você não precisa mexer na configuração principal do servidor. Sabe aquele arquivo httpd.conf que só o administrador do servidor tem acesso? Pois é, o .htaccess faz a mesma coisa, só que de um jeito mais acessível.

Quando ele foi criado lá nos primórdios da web, servia basicamente para controlar quem tinha permissão de acessar determinadas pastas. Com o tempo, virou um canivete suíço: hoje você usa para redirecionar páginas, bloquear IPs, criar URLs amigáveis, adicionar proteção por senha e uma porrada de outras coisas.

Tem só um detalhe importante: o servidor precisa ler esse arquivo toda vez que alguém acessa uma página. Se o seu site tem muito tráfego, isso pode deixar as coisas um pouco mais lentas. Nada absurdo, mas é bom saber. Para sites normais, a diferença é imperceptível.

Como o Apache trabalha com .htaccess

O Apache (que é o software do servidor web) tem um arquivo principal de configuração onde ficam todas as regras gerais. O .htaccess usa as mesmas regras, só que aplicadas a pastas específicas.

É tipo assim: imagine que o arquivo principal é a "lei federal" e o .htaccess são as "leis municipais". As municipais valem para aquela cidade específica, mas seguem a mesma estrutura da federal.

Isso é especialmente útil em hospedagem compartilhada. Nesse tipo de hospedagem, você divide o servidor com outros sites e não tem acesso ao arquivo principal. O .htaccess vira seu único jeito de customizar o comportamento do servidor.

Tem um porém: justamente por isso, alguns provedores de hospedagem desabilitam certas funcionalidades do .htaccess por questão de segurança ou performance. Se você tentar usar uma diretiva e não funcionar, pode ser por isso.

O ideal mesmo seria ter acesso ao arquivo principal de configuração e colocar suas regras lá. Mas como a maioria das pessoas usa hospedagem compartilhada, o .htaccess acaba sendo a solução mais prática.

Onde Fica o Arquivo .htaccess?

Agora que você já sabe o que é, vamos achar onde ele mora.

O diretório raiz do seu site

O lugar padrão do .htaccess é o diretório raiz – aquela pasta principal onde ficam todos os arquivos do seu site. Dependendo da hospedagem, ela pode se chamar public_html, www, htdocs ou até public.

É ali, junto com o arquivo index.html ou index.php, que você coloca o .htaccess principal.

Se você usa WordPress, o .htaccess fica no mesmo lugar das pastas wp-content, wp-includes e wp-admin. Aliás, o próprio WordPress já cria um arquivo .htaccess com algumas regras básicas quando você instala.

Dá para ter vários arquivos .htaccess espalhados pelo site. Por exemplo, você pode ter um na raiz controlando o site inteiro, e outro dentro da pasta /admin com regras específicas só para essa área. As regras são hierárquicas: o que está na raiz vale para tudo, mas pode ser sobrescrito por regras mais específicas nas subpastas.

Por que ele fica oculto

Arquivos que começam com ponto (.) são ocultos por padrão em sistemas Unix e Linux. Isso existe para proteger arquivos de sistema importantes – evita que alguém delete sem querer ou faça alguma besteira sem saber.

O problema é que você precisa ver esse arquivo para poder editá-lo. Dependendo de como você acessa seus arquivos, o processo é diferente.

Pelo cPanel (File Manager): clique no ícone de engrenagem (Settings) no canto superior direito e marque a caixa "Show Hidden Files (dotfiles)". Pronto, agora todos os arquivos ocultos vão aparecer na lista.

Por FTP (FileZilla, por exemplo): vá no menu Server e escolha "Force showing hidden files". Alguns clientes de FTP já mostram os arquivos ocultos por padrão, mas outros escondem.

Por SSH (linha de comando): use o comando ls -la em vez de só ls. O parâmetro -a força a listagem de tudo, inclusive os arquivos ocultos.

Depois de habilitar a visualização de ocultos, o .htaccess aparece normalmente na lista de arquivos.

Como Criar e Editar o .htaccess

Criando do zero

Abra qualquer editor de texto simples. No Windows, pode ser o Notepad mesmo. No Mac, o TextEdit (só lembre de colocar em modo texto simples, não Rich Text). No Linux, qualquer coisa tipo gedit, nano, vim…

A regra de ouro aqui é: nada de Word, Google Docs ou qualquer editor que adicione formatação. Esses programas colocam um monte de código invisível no arquivo que vai quebrar tudo no servidor.

Salve o arquivo com o nome .htaccess – só isso, sem nada antes, sem nada depois. Sem extensão .txt, .doc, nada.

Formato do arquivo: ASCII. Não UTF-8, não Unicode, ASCII puro. A maioria dos editores de texto já salva assim por padrão, mas vale conferir nas opções de salvamento.

Se o Windows ou Mac reclamar que não dá para salvar um arquivo só com ponto, tem um truque: salve como htaccess.txt, faça o upload para o servidor, e aí renomeie pelo painel de controle ou FTP, removendo o .txt. Funciona sempre.

Editando com segurança

Antes de qualquer coisa: backup. Sério mesmo, não pula essa parte.

Baixe o .htaccess atual para o seu computador ou faça uma cópia no próprio servidor (tipo .htaccess-backup). Um erro de digitação nesse arquivo pode derrubar o site inteiro com erro 500, e você vai querer ter como voltar atrás rapidinho.

Quando for editar, use comentários para documentar o que cada coisa faz. Comentários no .htaccess começam com #:

# Redireciona www para não-www
RewriteEngine On
RewriteCond %{HTTP_HOST} ^www\.(.*)$ [NC]
RewriteRule ^(.*)$ http://%1/$1 [R=301,L]

Isso pode parecer trabalheira extra, mas daqui a seis meses quando você olhar o arquivo de novo, vai agradecer.

Faz as mudanças aos poucos. Adiciona uma regra, salva, testa no navegador. Funcionou? Beleza, parte para a próxima. Quebrou? Desfaz e tenta de novo. Nunca adicione cinco regras de uma vez – se quebrar, você não vai saber qual foi o problema.

Depois de cada mudança, abre o site em modo anônimo do navegador (ou limpa o cache) e clica em algumas páginas diferentes. Testa o que você alterou e verifica se não quebrou nada sem querer.

Principais Usos do .htaccess

Redirecionamentos e URLs amigáveis

Redirecionamento 301 vs 302: o 301 é permanente. Quando você move uma página de lugar para sempre e quer que os buscadores saibam disso, usa 301. O Google entende que aquela URL velha não existe mais e passa toda a "força" da página antiga para a nova.

O 302 é temporário. É tipo "olha, por enquanto essa página está aqui, mas logo logo ela volta para o endereço original". Os buscadores não transferem a autoridade da página porque entendem que é provisório.

Para quase tudo, você vai querer o 301. O 302 é para situações bem específicas, tipo manutenção programada ou testes A/B.

www ou não-www: isso é mais importante do que parece. Se o seu site responde tanto em exemplo.com quanto em www.exemplo.com, o Google pode achar que são dois sites diferentes com conteúdo duplicado. Péssimo para SEO.

A solução é escolher um formato e forçar ele usando .htaccess. Não importa qual você escolhe, o que importa é ter só um.

URLs limpas: em vez de site.com/pagina.php?id=123&cat=noticias, você pode ter site.com/noticias/123. Fica mais bonito, mais fácil de lembrar e os buscadores gostam mais.

O WordPress já faz isso automaticamente usando o .htaccess. Se você programa, pode criar suas próprias regras de reescrita.

Segurança e controle de acesso

Bloquear IPs específicos: tá recebendo ataque de um IP chato? Bloqueia ele. É especialmente útil contra tentativas de invasão por força bruta – aqueles robôs que ficam tentando adivinhar senha de admin.

A cada IP bloqueado, menos carga no seu servidor. E menos dor de cabeça para você.

Proteger contra hotlinking: hotlinking é quando outro site usa suas imagens diretamente. Tipo assim: o cara põe no blog dele uma tag <img> apontando para uma imagem no seu servidor. A imagem aparece no site dele, mas quem paga a conta da banda é você.

Com o .htaccess, você bloqueia isso. Aí se alguém tentar fazer hotlinking, aparece uma imagem quebrada ou uma mensagem que você escolher.

Isso economiza banda (que pode economizar dinheiro se você paga por tráfego) e impede que usem seu conteúdo sem permissão.

Bloquear bots maliciosos: tem uma lista enorme de bots ruins na internet: raspadores de conteúdo, spammers, bots que só querem consumir recursos… Você pode adicionar regras no .htaccess para bloquear centenas deles de uma vez.

Obviamente, você não quer bloquear os bots do Google, Bing e outros buscadores legítimos. Só os ruins mesmo.

Proteção por senha

Quer que uma pasta do seu site peça usuário e senha antes de permitir o acesso? O .htaccess resolve.

Você cria dois arquivos: o .htaccess com as regras, e o .htpasswd com os usuários e senhas (criptografadas, óbvio). Quando alguém tenta acessar aquela pasta, aparece aquela janelinha de login do navegador.

Super útil para:

• Área administrativa do site
• Área de clientes
• Site de homologação que ainda não é público
• Qualquer coisa que precisa ficar escondida da internet

Páginas de erro personalizadas

Sabe quando você entra num link quebrado e aparece aquela página branca escrito "404 Not Found"? Ou quando o servidor dá problema e aparece "500 Internal Server Error"?

Com o .htaccess, você cria páginas bonitas e úteis para esses erros. Em vez de uma mensagem genérica, você pode ter uma página com o design do seu site, um buscador, links para as páginas principais…

O visitante continua tendo uma experiência ruim (afinal, deu erro), mas pelo menos não parece que seu site é amador ou tá quebrado.

Os erros mais comuns para customizar são:

• 404 (página não encontrada)
• 403 (acesso negado)
• 500 (erro interno do servidor)
• 503 (serviço indisponível)

Comparação Rápida: Quando Usar Cada Recurso

Armadilhas Comuns e Como Evitar

Já que estamos falando de .htaccess, vale mencionar os erros mais comuns que todo mundo comete no começo.

Erro de sintaxe

O Apache é bem chato com sintaxe. Uma vírgula fora do lugar, um espaço a mais, uma diretiva escrita errada… pronto, erro 500 no site inteiro.

Antes de subir qualquer mudança, dá uma conferida básica:

• As diretivas estão escritas corretamente?
• Os parênteses e colchetes estão fechados?
• As barras estão no lugar certo?

Se quebrar mesmo assim, volta para o backup e tenta de novo com mais calma.

Conflito entre regras

Às vezes você adiciona uma regra nova que entra em conflito com uma que já estava lá. O resultado pode ser comportamento estranho: redirecionamento em loop, algumas páginas funcionando e outras não…

Por isso a importância de testar depois de cada mudança. Se você adiciona dez regras de uma vez e quebra, vai ser um saco descobrir qual foi o problema.

Cache do navegador

Você fez a mudança, testou, e… não funcionou. Mas calma. Antes de sair reescrevendo tudo, tenta acessar em modo anônimo ou limpa o cache do navegador.

Às vezes a mudança funcionou, mas o navegador tá mostrando a versão antiga da página porque ela tá em cache.

Performance em sites grandes

Se o seu site tem dezenas de milhares de páginas e muito tráfego, o .htaccess pode se tornar um gargalo. Nesse caso, vale a pena conversar com quem cuida do servidor para colocar as regras no arquivo principal de configuração.

Mas isso só vira problema em sites realmente grandes. Para a maioria dos sites normais, o impacto é insignificante.

Exemplos Práticos de Código

Forçar HTTPS

# Força todas as páginas a usarem HTTPS
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Isso pega qualquer requisição que chegar via HTTP normal e redireciona para HTTPS. Importante para segurança e para o Google (que dá preferência para sites com HTTPS).

Redirecionar www para não-www

# Remove www do endereço
RewriteEngine On
RewriteCond %{HTTP_HOST} ^www\.(.*)$ [NC]
RewriteRule ^(.*)$ https://%1/$1 [R=301,L]

Ou se você preferir o contrário (não-www para www):

# Adiciona www no endereço
RewriteEngine On
RewriteCond %{HTTP_HOST} ^(?!www\.)(.+) [NC]
RewriteRule ^(.*)$ https://www.%1/$1 [R=301,L]

Bloquear IP específico

# Bloqueia um IP chato
order allow,deny
deny from 123.456.789.0
allow from all

Troca 123.456.789.0 pelo IP que você quer bloquear. Dá para adicionar vários IPs, um por linha.

Páginas de erro personalizadas

# Define páginas de erro customizadas
ErrorDocument 404 /erro-404.html
ErrorDocument 403 /erro-403.html
ErrorDocument 500 /erro-500.html

Cria os arquivos HTML personalizados e coloca o caminho deles aí.

Proteção por senha

No .htaccess:

# Pede senha para acessar esta pasta
AuthType Basic
AuthName "Área Restrita"
AuthUserFile /caminho/completo/.htpasswd
Require valid-user

Você precisa criar o arquivo .htpasswd com as senhas criptografadas. A maioria dos painéis de controle de hospedagem tem uma ferramenta para gerar esse arquivo automaticamente.

Quando NÃO Usar .htaccess

Nem sempre o .htaccess é a melhor solução.

Se você tem acesso root ao servidor (VPS ou servidor dedicado), é melhor colocar as regras no arquivo de configuração principal do Apache. É mais rápido e mais eficiente.

O .htaccess é mais prático para quem tem hospedagem compartilhada e não tem outra opção.

Outra situação: se você tá usando Nginx em vez de Apache, o .htaccess não funciona. O Nginx tem seu próprio sistema de configuração, completamente diferente.

E se você usa um construtor de sites tipo Wix, Squarespace, WordPress.com (não o .org), Shopify… essas plataformas não dão acesso ao .htaccess porque tudo já é gerenciado por elas.

Perguntas Frequentes sobre .htaccess

O .htaccess é obrigatório para o site funcionar?

Não. Muitos sites funcionam perfeitamente sem nenhum arquivo .htaccess. Ele só é necessário quando você quer fazer customizações específicas: redirecionamentos, proteções, URLs amigáveis, essas coisas.

Se você tá começando um site do zero e não sabe se precisa, provavelmente não precisa ainda.

Posso deletar o .htaccess sem problema?

Tecnicamente sim, o site continua funcionando. Mas você vai perder todas as customizações que estavam ali. Se o WordPress criou o arquivo para fazer os permalinks bonitos funcionarem, deletar vai quebrar todas as URLs do site (exceto a home).

Se não tem certeza do que tem dentro, melhor não deletar. No máximo, renomeia para .htaccess-old e vê o que quebra. Aí você sabe o que era importante.

Como sei que meu .htaccess está funcionando?

Faz uma mudança simples e testa. Por exemplo, adiciona um redirecionamento de teste de uma página para outra.

Se funcionar, é porque tá lendo o arquivo direitinho.

Se não funcionar, pode ser que o Apache não esteja permitindo uso de .htaccess naquela pasta, você está num servidor Nginx (que não usa .htaccess), ou tem algum erro de sintaxe no arquivo.

Preciso reiniciar algo depois de editar?

Não. As mudanças no .htaccess entram em vigor imediatamente. É só salvar o arquivo e recarregar a página no navegador (de preferência forçando atualização com Ctrl+F5 ou Cmd+Shift+R).

Dá para usar .htaccess em subpastas?

Dá sim. Você pode ter um .htaccess na raiz do site e outros em subpastas. As regras da subpasta complementam (ou sobrescrevem) as regras da pasta pai.

Exemplo: você tem um .htaccess na raiz forçando HTTPS. Aí cria outro na pasta /admin pedindo senha. As duas coisas vão funcionar juntas – vai exigir HTTPS E senha para acessar /admin.

Qual é o tamanho máximo do arquivo?

Não existe limite de tamanho fixo, mas quanto maior o arquivo, mais lento fica para o servidor processar. Na prática, a maioria dos arquivos .htaccess tem menos de 100 linhas.

Se o seu tá passando de 500 linhas, provavelmente tá fazendo algo errado ou deveria estar usando o arquivo de configuração principal do Apache em vez do .htaccess.

Como eu criptografo as senhas do .htpasswd?

Não cria na mão. A maioria dos painéis de hospedagem (cPanel, Plesk, etc) tem uma ferramenta para gerar o arquivo .htpasswd automaticamente. Ou usa um gerador online – procura por "htpasswd generator". O importante é nunca, jamais, colocar senhas em texto puro. Sempre use a versão criptografada.

Conclusão

O .htaccess é uma ferramenta simples, mas poderosa. Com um arquivo de texto de algumas linhas, você consegue controlar aspectos importantes do seu site: segurança, URLs, redirecionamentos, performance…

A curva de aprendizado não é tão íngreme quanto parece. Começa com o básico – um redirecionamento aqui, uma página de erro ali – e vai pegando o jeito aos poucos.

Lembra sempre das regras de ouro:

• Backup antes de qualquer mudança
• Uma mudança de cada vez
• Testa depois de cada alteração
• Documenta o que cada coisa faz

Com o tempo, mexer no .htaccess vira rotina. E quando você dominar, vai ter muito mais controle sobre como seu site se comporta.

Agora é só praticar. Cria um arquivo de teste, experimenta algumas regras básicas, vê como funciona. A melhor forma de aprender é fazendo – só não esquece do backup!