DocumentationCommerceCommerce on Cloud Guide

Custom VCL to bypass Fastly cache

Last update: May 14, 2026

CREATED FOR:

  • Admin
  • Developer

You can create a custom VCL snippet to bypass the Fastly cache so you can troubleshoot request traffic to the origin server. For example, you can create a snippet to determine whether site issues are caused by caching, or to troubleshoot headers.

You can configure the snippet to bypass Fastly caching for requests from a specific IP address or URL.

NOTE
Before merging custom VCL configuration into a production environment, make sure to test the code in the Staging environment.

Prerequisites:

  • Seu ambiente deve ser configurado para usar o Fastly CDN. Consulte Configurar serviços do Fastly.

  • Verifique se você está executando a versão mais recente do módulo CDN Fastly para o Magento 2. Consulte Atualizar o Módulo Fastly.

  • Verifique a configuração do ambiente para o serviço Fastly. Consulte Verificar cache rápido.

  • Você deve ter credenciais de Administrador para acessar os ambientes de Preparo e Produção.

To bypass Fastly cache based on IP address or URL:

  1. Log in to the Admin.

  2. Click Stores > Settings > Configuration > Advanced > System.

  3. Expand Full Page Cache > Fastly Configuration > Custom VCL Snippets.

  4. Click Create Custom Snippet.

  5. Add the VCL snippet values:

    • Name — bypass_fastly

    • Type — recv

    • Priority — 5

    • VCL snippet content —

      The following example bypasses Fastly for a specific IP address:

      code language-conf 
      if (client.ip == "<Your IPv4 IP address>" || client.ip == "<Your IPv6 IP address>") {
  return(pass);
}

      The following example bypasses Fastly for a specific URL pattern:

      code language-conf 
      if (req.url ~ "/media/feeds/GoogleShoppingHiVisNew.xml") {  return (pass);}

      For an exact URL match, use the == operator instead of the ~ operator. See the Fastly VCL reference for details.

  6. Click Create.

    Create Fastly Bypass VCL snippet

  7. After the page reloads, click Upload VCL to Fastly in the Fastly Configuration section.

  8. After the upload completes, refresh the cache according to the notification at the top of the page.

    Fastly validates the updated VCL version during the upload process. If the validation fails, edit your custom VCL snippet to fix any issues. Then, upload the VCL again.

After you add the VCL snippet, you can use cURL commands to submit requests to the origin server from the specified IP address or URL as shown in the following example:

curl -svo /dev/null www.example.com/index.html

Then, inspect the response to troubleshoot issues with the uncached content.

NOTE
Instead of manually uploading custom VCL snippets, you can add snippets to the $MAGENTO_CLOUD_APP_DIR/var/vcl_snippets_custom directory in your environment. Snippets in this directory upload automatically when you click upload VCL to Fastly in the Commerce Admin. See Automated custom VCL snippets deployment in the Fastly CDN module for Magento 2 documentation.

Modificar o trecho de VCL personalizado

  1. Faça logon no Administrador.

  2. Clique em Lojas > Configurações > Configuração > Avançadas > Sistema.

  3. Expanda Cache de Página Inteira > Configuração Rápida > Trechos de VCL Personalizados.

    Gerenciar trechos de VCL personalizados

  4. Na coluna Ação, clique no ícone de configurações ao lado do trecho a ser editado.

  5. Depois que a página for recarregada, clique em Carregar VCL para Fastly na seção Configuração Fastly.

  6. Depois que o upload for concluído, atualize o cache de acordo com a notificação na parte superior da página.

WARNING
A opção Custom VCL snippets UI mostra apenas os trechos adicionados pelo Administrador do Adobe Commerce. Se você adicionar trechos usando a API Fastly, use a API para gerenciá-los.

Excluir o trecho de VCL personalizado

  1. Faça logon no Administrador.

  2. Clique em Lojas > Configurações > Configuração > Avançadas > Sistema.

  3. Expanda Cache de Página Inteira > Configuração Rápida > Trechos de VCL Personalizados.

    Gerenciar trechos de VCL personalizados

  4. Na coluna Ação, clique no ícone de lixeira ao lado do trecho a ser excluído.

  5. Na próxima janela modal, clique em DELETE e ative uma nova versão.

WARNING
A opção Custom VCL snippets UI mostra apenas os trechos adicionados pelo Administrador do Adobe Commerce. Se você adicionar trechos usando a API Fastly, use a API para gerenciá-los.
recommendation-more-help
commerce-on-cloud-help-cloud-guide