Configure an Apache caching policy - : Central de Documentação do Alibaba Cloud

Configure o mod_expires ou o mod_headers no servidor de origem Apache para definir os cabeçalhos de resposta Cache-Control e Expires. Dessa forma, os nós de borda do Alibaba Cloud CDN e os navegadores armazenam em cache o conteúdo estático com o TTL (Tempo de Vida) adequado.

Escolha um módulo

O Apache oferece dois módulos para controlar cabeçalhos de cache. Escolha conforme suas necessidades:

Módulo	Vantagens	Desvantagens	Quando usar
`mod_expires`	Sintaxe simples; define rapidamente `Expires` e `Cache-Control: max-age` por tipo MIME	Não permite diretivas complexas como `no-store` ou `immutable`	Cenários simples que exigem apenas `max-age`
`mod_headers`	Controle total do cabeçalho `Cache-Control`; suporta todas as diretivas, incluindo `immutable`	Sintaxe um pouco mais complexa	Ambientes de produção que demandam políticas de cache detalhadas

Pré-requisitos

Antes de começar, verifique se os módulos necessários do Apache estão ativados.

Confira quais módulos estão carregados:

apachectl -M | grep -E "expires|headers"

A saída deve incluir expires_module e headers_module. Se algum estiver ausente, ative-o:

Debian / Ubuntu:

  sudo a2enmod headers expires
  sudo systemctl restart apache2

CentOS / RHEL / Alibaba Cloud Linux:

Geralmente, os módulos já vêm compilados por padrão. Caso algum esteja faltando, verifique o diretório /etc/httpd/conf.modules.d/ e garanta que a linha LoadModule correspondente não esteja comentada. Em seguida, reinicie o Apache:

  sudo systemctl restart httpd

Nota

Coloque a configuração em um arquivo dedicado dentro de /etc/httpd/conf.d/ (CentOS/RHEL) ou /etc/apache2/conf-available/ (Debian/Ubuntu) — por exemplo, cache.conf. Evite arquivos .htaccess: o Apache processa o .htaccess a cada requisição, o que gera sobrecarga desnecessária e anula os ganhos de desempenho esperados.

Exemplos de configuração

Todos os exemplos utilizam blocos <IfModule> para garantir que o Apache inicie sem erros mesmo na ausência do módulo. Substitua ou estenda as linhas ExpiresByType para corresponder aos seus tipos de conteúdo.

Defina TTL de cache por tipo de conteúdo

Use o mod_expires para regras simples de max-age ou o mod_headers quando precisar de controle total sobre o Cache-Control.

**mod_expires**

<IfModule mod_expires.c>
    ExpiresActive On

    # Default TTL for all content types
    ExpiresDefault "access plus 1 day"

    # Images: cache for 1 month
    ExpiresByType image/jpeg "access plus 1 month"
    ExpiresByType image/png  "access plus 1 month"
    ExpiresByType image/gif  "access plus 1 month"
    ExpiresByType image/svg+xml "access plus 1 month"
    ExpiresByType image/webp "access plus 1 month"

    # CSS and JavaScript: cache for 1 week
    ExpiresByType text/css              "access plus 1 week"
    ExpiresByType application/javascript "access plus 1 week"

    # Fonts: cache for 1 year
    ExpiresByType font/woff2 "access plus 1 year"
    ExpiresByType font/woff  "access plus 1 year"

    # HTML and data: do not cache
    ExpiresByType text/html        "access plus 0 seconds"
    ExpiresByType application/json "access plus 0 seconds"
</IfModule>

**Equivalente com mod_headers**

<IfModule mod_headers.c>
    # Images
    <FilesMatch "\.(jpg|jpeg|png|gif|svg|webp)$">
        Header set Cache-Control "max-age=2592000, public"
    </FilesMatch>

    # CSS and JavaScript
    <FilesMatch "\.(css|js)$">
        Header set Cache-Control "max-age=604800, public"
    </FilesMatch>

    # Fonts
    <FilesMatch "\.(woff|woff2)$">
        Header set Cache-Control "max-age=31536000, public, immutable"
    </FilesMatch>

    # HTML and data: no caching
    <FilesMatch "\.(html|json)$">
        Header set Cache-Control "no-store"
    </FilesMatch>
</IfModule>

Defina um TTL padrão global

Se a maior parte do seu conteúdo for estática, defina um padrão global e substitua tipos específicos conforme necessário.

**mod_expires**

<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresDefault "access plus 1 week"
</IfModule>

**Equivalente com mod_headers**

<IfModule mod_headers.c>
    Header set Cache-Control "max-age=604800, public"
</IfModule>

Desativar cache para conteúdo dinâmico

Impeça que os nós de borda da CDN e os navegadores façam cache de respostas que mudam a cada requisição.

**mod_expires**

<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/html        "access plus 0 seconds"
    ExpiresByType application/json "access plus 0 seconds"
</IfModule>

**Equivalente com mod_headers**

<IfModule mod_headers.c>
    <FilesMatch "\.(html|json|php)$">
        Header set Cache-Control "no-store"
    </FilesMatch>
</IfModule>

Referência de diretivas

Diretivas do `mod_expires`

Diretiva	Descrição
`ExpiresActive On`	Ativa a geração do cabeçalho `Expires` para o bloco de servidor ou localização
`ExpiresDefault "<base> plus <duration>"`	Define o TTL padrão para todos os tipos de conteúdo não correspondidos por `ExpiresByType`
`ExpiresByType <MIME-type> "<base> plus <duration>"`	Especifica o TTL para um tipo MIME específico

Opções de base de tempo:

Valor	Significado
`access` / `now`	O TTL é calculado a partir do momento da requisição
`modification`	O TTL é calculado a partir do carimbo de data/hora da última modificação do arquivo

Unidades de duração: years, months, weeks, days, hours, minutes, seconds

Valores comuns de duração:

Expressão	Equivalente	Caso de uso
`"access plus 1 year"`	31.536.000 segundos	Recursos versionados com nomes de arquivo para invalidação de cache
`"access plus 1 month"`	2.592.000 segundos	Imagens e outros recursos atualizados com pouca frequência
`"access plus 1 week"`	604.800 segundos	Arquivos CSS e JavaScript
`"access plus 0 seconds"`	Sem cache	Páginas HTML e respostas de API

Verifique a configuração

Após recarregar o Apache, confirme se os cabeçalhos estão presentes na resposta:

curl -I https://<your-domain>/path/to/static-file.jpg

Procure por Cache-Control ou Expires na saída:

HTTP/1.1 200 OK
Cache-Control: max-age=2592000, public
Expires: Thu, 10 Jul 2026 04:00:00 GMT

Alternativamente, abra o Chrome DevTools, acesse a aba Network, recarregue a página e clique em um recurso estático. O painel Response Headers exibe os valores de Cache-Control e Expires definidos pela sua configuração.

Melhores práticas

**Prefira o mod_headers em produção.** Ele suporta toda a gama de diretivas Cache-Control (no-store, immutable, stale-while-revalidate) que o mod_expires não consegue gerar.
Adote TTLs longos para recursos versionados. Se seu pipeline de build adiciona um hash aos nomes dos arquivos (por exemplo, app.a1b2c3.js), defina TTLs de um ano ou mais. A alteração no nome do arquivo funciona como um mecanismo de invalidação de cache.
**Defina no-store para HTML e respostas de API.** Isso garante que navegadores e nós de borda da CDN sempre busquem a estrutura e os dados mais recentes da página.
Recarregue, não reinicie. Após editar o arquivo de configuração, execute apachectl graceful (ou systemctl reload apache2 / systemctl reload httpd) para aplicar as alterações sem encerrar conexões ativas.
**Teste com curl -I antes de ir para produção.** Valide os cabeçalhos em cada tipo de conteúdo configurado, não apenas em um.

Escolha um módulo

Pré-requisitos

Exemplos de configuração

Defina TTL de cache por tipo de conteúdo

Defina um TTL padrão global

Desativar cache para conteúdo dinâmico

Referência de diretivas

Diretivas do mod_expires

Verifique a configuração

Melhores práticas

Diretivas do `mod_expires`