Gerador .htaccess

O que é um .htaccess ?

O arquivo .htaccess é um arquivo de configuração para servidores web Apache. Ele permite definir redirecionamentos de URL, cabeçalhos de segurança, regras de cache e mais · sem modificar a configuração principal do servidor.

Perguntas frequentes

Onde colocar o arquivo .htaccess ?

Coloque-o no diretório raiz do seu site (geralmente public_html ou www). As regras se aplicam a esse diretório e a todos os seus subdiretórios.

Isso funciona com o Nginx ?

Não. O .htaccess é específico do Apache. O Nginx usa sua própria sintaxe de configuração em nginx.conf ou nos arquivos de configuração de site.

O .htaccess pode deixar meu site mais lento ?

O Apache verifica o .htaccess a cada requisição, então arquivos muito grandes podem adicionar sobrecarga. Para sites com muito tráfego, mover as regras para a configuração principal do Apache é mais rápido.

O que o .htaccess realmente é

Um arquivo .htaccess é o arquivo de configuração por diretório do Apache. O nome é amplamente entendido como uma contração de «hypertext access» (acesso a hipertexto), refletindo o uso original e primário do arquivo de restringir o acesso a documentos de hipertexto. Coloque um em qualquer diretório e as diretivas se aplicam àquele diretório e a cada subdiretório abaixo dele. O arquivo não tem nome antes do ponto (é um dot-file do Unix, oculto por padrão) e precisa se chamar exatamente .htaccess (em minúsculas, com ponto inicial) para que o Apache o encontre sob a configuração padrão AccessFileName.

Há um custo de desempenho real. A documentação do Apache é explícita: «se o AllowOverride está configurado para permitir o uso de arquivos .htaccess, o Apache vai procurar em todos os diretórios por arquivos .htaccess. Assim, permitir arquivos .htaccess causa um impacto no desempenho, quer você realmente os use ou não.» A árvore de diretórios é percorrida a cada requisição HTTP. Para uma requisição a /var/www/html/foo/bar/baz.html, o Apache faz verificações stat em /.htaccess, depois /var/.htaccess, depois /var/www/.htaccess, depois /var/www/html/.htaccess, e assim por diante, mesmo quando nenhum desses arquivos existe. A própria recomendação do Apache é usar blocos <Directory> da configuração principal onde for possível (analisados uma vez na inicialização) e reservar o .htaccess para ambientes de hospedagem em que você não tem acesso à configuração principal.

Quando você precisa dele (e quando não)

O Apache lista dois casos de uso legítimos para o .htaccess: provedores de hospedagem dando aos usuários um controle limitado sem acesso total à configuração do servidor, e casos em que as diretivas precisam diferir entre subdiretórios onde quem implanta controla apenas o sistema de arquivos. Fora esses, a documentação recomenda explicitamente mover as regras para blocos <Directory> na configuração principal.

O nginx (o segundo servidor web mais popular) não suporta o .htaccess de jeito nenhum; ele rejeita deliberadamente arquivos de configuração por diretório por motivos de desempenho, e toda a configuração vive no nginx.conf e em quaisquer arquivos de site incluídos. Se o seu projeto está no nginx, a saída deste gerador não vai ajudar: você vai precisar de blocos server / location no arquivo de configuração do nginx. O Caddy usa a sua própria sintaxe Caddyfile, com HTTPS automático via Let's Encrypt como padrão. O LiteSpeed e o OpenLiteSpeed suportam o .htaccess para compatibilidade com o Apache. O IIS usa o web.config.

Reescrita de URL e o padrão canônico de HTTPS

A maior parte do trabalho não trivial com .htaccess usa o mod_rewrite, o motor de reescrita de URL baseado em regras do Apache, construído sobre expressões regulares estendidas POSIX. A forma básica é RewriteRule pattern substitution [flags], opcionalmente precedida por uma ou mais condições RewriteCond. O bloco padrão para forçar o HTTPS:

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

As flags [L,R=301] significam «esta é a última regra desta rodada» e «responda com HTTP 301 Moved Permanently». Um 301 é a escolha certa para redirecionamentos permanentes: os motores de busca passam a equidade de link e os navegadores fazem cache de forma agressiva. Use o 302 (Found) apenas para redirecionamentos genuinamente temporários, em que você não quer que a mudança seja armazenada em cache.

Atrás de um balanceador de carga ou de um proxy reverso que encerra o TLS, o servidor de origem vê HTTP puro mesmo quando o navegador do usuário está em HTTPS: uma regra RewriteCond %{HTTPS} off ingênua então redireciona para sempre. A correção é, em vez disso, verificar o cabeçalho encaminhado: RewriteCond %{HTTP:X-Forwarded-Proto} !https. O modo «Flexible SSL» da Cloudflare (o CDN fala HTTP com a origem enquanto o usuário usa HTTPS) é a causa mais comum dessa armadilha de loop de redirecionamento.

Escolha entre a canonicalização com www e sem www com um padrão semelhante. Escolha um nome de host canônico para o SEO (evita problemas de conteúdo duplicado) e para o escopo de cookie (um subdomínio www recebe cookies diferentes do apex por padrão).

Compressão e cache

O mod_deflate comprime com gzip as respostas textuais, reduzindo drasticamente o tamanho de transferência em text/HTML/CSS/JS. Envolva o bloco em <IfModule mod_deflate.c> para que ele não derrube o site em servidores onde o módulo não está carregado. O Brotli (mod_brotli) é o substituto moderno e usa o mesmo padrão.

O mod_expires define os cabeçalhos Expires e Cache-Control: max-age. A sintaxe amplamente usada «access plus 1 year» significa que o asset pode ficar em cache por um ano a partir do momento em que o usuário o buscou. Um max-age longo está correto para nomes de arquivo de assets com hash (app.abc123.js); um max-age mais curto está correto para HTML e qualquer coisa mutável. Para um controle mais fino, Header set Cache-Control "public, max-age=31536000, immutable" em arquivos com hash é a melhor prática moderna.

Cabeçalhos de segurança que vale a pena conhecer

• X-Frame-Options: SAMEORIGIN: impede que a página seja incorporada em <iframe> em outras origens. Em grande parte substituído pelo frame-ancestors da CSP.
• Content-Security-Policy: a principal defesa moderna contra XSS e clickjacking. Um ponto de partida: default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'. Aperte com o tempo.
• Strict-Transport-Security (HSTS): diz ao navegador para só falar HTTPS com o seu domínio. max-age=31536000; includeSubDomains é a base típica. Adicione preload apenas quando você tem certeza de que o HTTPS é permanente: uma vez pré-carregado na lista HSTS do navegador, a remoção é difícil.
• X-Content-Type-Options: nosniff: impede que os navegadores fiquem adivinhando o cabeçalho Content-Type. O cabeçalho tem apenas um valor.
• Referrer-Policy: strict-origin-when-cross-origin: o padrão moderno; envia a URL completa para requisições de mesma origem, apenas a origem para requisições de origem cruzada, e nada no rebaixamento de HTTPS para HTTP.
• Permissions-Policy: controla recursos do navegador como câmera, microfone, geolocalização. Substituiu o antigo cabeçalho Feature-Policy.
• X-XSS-Protection: em grande parte obsoleto. O filtro foi removido do Chrome e nunca existiu no Firefox; a segurança moderna depende da CSP. Muitos guias antigos ainda o incluem para o IE legado, seguro de omitir em sites novos.

Esconda o que não deveria ser servido

Dois comandos de uma linha de reforço de segurança se pagam:

• Options -Indexes: desativa as listagens de diretório geradas automaticamente quando não há um index.html. Muitas distribuições vêm com a indexação de diretórios ligada por padrão; um diretório perdido e desprotegido não deveria vazar o seu conteúdo para a web.
• Bloqueie dot-files e metadados de controle de versão. Um bloco <FilesMatch "^(\.htaccess|\.htpasswd|\.env|\.git.*)$"> com Require all denied impede que os atacantes baixem o .env (que muitas vezes contém senhas de banco de dados e chaves de API) ou o .git/config (que expõe URLs remotas e, às vezes, credenciais). Os relatórios de ameaças da Akamai e do SANS documentam a exposição do .env como um dos vazamentos na camada de aplicação mais comuns dos anos 2020.

O Apache 2.4 substituiu a antiga sintaxe Order Allow,Deny pela família mais limpa de diretivas Require: Require all granted, Require all denied, Require ip 192.0.2.0/24, Require not ip 198.51.100.5. A sintaxe antiga ainda funciona por compatibilidade retroativa, mas é documentada como obsoleta.

Armadilhas comuns

• O mod_rewrite precisa estar habilitado no nível do servidor. No Debian/Ubuntu: sudo a2enmod rewrite && sudo systemctl restart apache2. Sem ele, cada RewriteRule é silenciosamente ignorada.
• O AllowOverride importa. Se a configuração principal tem AllowOverride None para o seu <Directory>, cada diretiva no seu .htaccess é silenciosamente ignorada. O AllowOverride All permite tudo; o AllowOverride FileInfo AuthConfig permite apenas a reescrita e a autenticação, o que é suficiente para a maioria dos casos de uso.
• Um único erro de digitação quebra o site inteiro. O Apache retorna um 500 Internal Server Error para cada requisição à árvore de diretórios afetada até o arquivo ser corrigido. Sempre teste primeiro em um ambiente de teste; mantenha uma cópia de backup chamada .htaccess.bak; tenha acesso SSH/FTP à mão para poder renomear um arquivo quebrado remotamente. Fique de olho no /var/log/apache2/error.log para mensagens de sintaxe.
• Loops infinitos de redirecionamento. Os navegadores limitam as cadeias de redirecionamento em cerca de 20 saltos e mostram ERR_TOO_MANY_REDIRECTS. As causas mais comuns: regra de redirecionamento HTTPS rodando em um servidor atrás de um proxy que encerra o TLS (use %{HTTP:X-Forwarded-Proto}); regras de www e de HTTPS na ordem errada, causando redirecionamentos duplos; o modo Flexible SSL da Cloudflare.
• A flag [L] executa o motor de reescrita de novo a partir do topo, com a URL reescrita. Se uma regra posterior então casar, o comportamento pode ser surpreendente. Use [END] (Apache 2.3.9+) quando você realmente quer uma parada total.
• O contexto por diretório remove a barra inicial. No .htaccess, RewriteRule ^index\.html$ home.html casa; RewriteRule ^/index\.html$ não casa. Isso confunde todo mundo que copia uma regra de um exemplo da configuração principal.
• Algumas diretivas são proibidas no .htaccess: <VirtualHost>, <Directory>, <Location>, Listen, ServerName são exclusivas da configuração principal. O arquivo por diretório já se aplica implicitamente ao seu próprio diretório.

Mais perguntas

Onde exatamente o arquivo deve ficar?

No diretório cujo conteúdo você quer controlar. A maioria dos usuários de hospedagem compartilhada o coloca na raiz do documento do seu site, public_html/, www/ ou htdocs/, dependendo do host. O Apache então percorre a árvore de diretórios aplicando as regras àquele diretório e a cada subdiretório abaixo dele.

301 ou 302, qual redirecionamento devo usar?

301 Moved Permanently para mudanças permanentes. Os motores de busca transferem a equidade de link para a nova URL; os navegadores fazem cache do redirecionamento de forma agressiva. Use isto para casos do tipo «movemos esta página para sempre». 302 Found para redirecionamentos temporários: o navegador não faz cache e os motores de busca não transferem o ranking. Use o 302 apenas quando a mudança é realmente temporária; usar o 302 em vez do 301 por padrão é um dos gols contra de SEO mais comuns.

Como eu protejo um diretório com senha?

Crie um arquivo .htpasswd com o utilitário de linha de comando htpasswd (ele armazena linhas username:bcrypt-hash) e guarde-o fora da sua raiz web. Depois, no .htaccess: AuthType Basic, AuthName "Restricted Area", AuthUserFile /full/path/to/.htpasswd, Require valid-user. O navegador mostra um prompt de autenticação Basic do sistema a qualquer um que visite o diretório. Este é o padrão clássico do Apache; para uma autenticação séria, considere, em vez disso, um sistema de login no nível da aplicação.

Isto vai funcionar no WordPress?

O WordPress vem com o seu próprio bloco .htaccess (entre os marcadores # BEGIN WordPress e # END WordPress) que cuida dos permalinks. O WordPress vai sobrescrever qualquer coisa dentro desses marcadores quando você salvar as configurações de permalinks. Adicione as suas próprias regras fora dos marcadores do WordPress (tipicamente acima deles) para que elas sobrevivam à regeneração automática.

Algo é enviado a um servidor?

Não. O gerador é JavaScript que monta blocos de diretivas com base nas suas caixas de seleção; a saída é construída no seu navegador. Nada sobre o seu domínio ou as opções escolhidas sai da página; a ferramenta funciona offline depois de carregada.

Ferramentas relacionadas