# Como corrigir scripts externos quebrados ao remover query strings no WP Rocket

As query strings do WP Rocket quebram scripts externos quando a otimização de arquivos (Minify e Combine de JavaScript) reescreve ou agrupa URLs de terceiros, fazendo o navegador deixar de carregar o arquivo original versionado. A correção e excluir esses arquivos da otimização.

## O que é query strings do WP Rocket quebrando scripts externos?

Query strings são os parametros que seguem o ponto de interrogacao na URL de um arquivo estático, como ?ver=1.4.2 em script.js?ver=1.4.2. No WordPress elas servem de cache busting: quando a versão muda, a URL muda e o navegador busca o arquivo novo em vez de servir uma copia antiga do cache. Scripts externos (Google Analytics, pixels, widgets de chat, bibliotecas de CDN) dependem dessa URL versionada exata para carregar a versão correta.

O problema com o WP Rocket não vem de uma opção isolada de remover query strings, e sim da otimização de arquivos: ao combinar (Combine JavaScript Files) ou minificar (Minify JavaScript Files) recursos, o plugin pode agrupar ou reescrever a URL de um script de terceiros, deixando o arquivo original com sua query string de fora. O navegador entao falha ao carregar o recurso e a função quebra, exibindo erro no console. A documentação oficial do WP Rocket trata isso indicando a exclusão do arquivo externo da otimização pela URL completa ou pelo domínio.

## Como identificar

- No console do navegador (F12 -> Console) aparece um erro de carregamento do tipo 'Failed to load resource' ou 'net::ERR_ABORTED' apontando para o arquivo .js de um serviço externo.
- Um recurso de terceiros para de funcionar após ativar o WP Rocket: o chat ao vivo não abre, o formulário não envia, o mapa não renderiza ou o pixel de conversao deixa de disparar.
- O erro 'Uncaught ReferenceError: <função> is not defined' surge porque o script externo combinado carregou fora de ordem ou não carregou.
- Ao desativar 'Combine JavaScript Files' ou 'Minify JavaScript Files' no WP Rocket, o recurso externo volta a funcionar imediatamente.
- Ferramentas de auditoria (PageSpeed Insights, GTmetrix) listam o arquivo de terceiros com a URL alterada ou ausente em relacao a versão sem o plugin.

**Antes de começar:** Antes de alterar a otimização de arquivos ou adicionar exclusoes em producao, faca um backup do site ou teste primeiro em staging, porque mexer no Combine e no Minify do JavaScript pode afetar o carregamento de vários recursos da página ao mesmo tempo.

## Como prevenir

- Ative a otimização de arquivos do WP Rocket de forma incremental, validando cada opção (Minify e Combine de JS) com o console aberto antes de aplicar em producao.
- Mantenha uma lista documentada dos scripts de terceiros do site (analytics, chat, pixels, CDNs) e já deixe-os no campo 'Excluded JavaScript Files' ao subir o site.
- Prefira excluir o recurso externo da otimização a desligar o Combine e o Minify para o site inteiro, preservando o ganho de performance nas demais páginas.
- Após cada atualização de plugin de terceiros ou troca de CDN, revise as exclusoes do WP Rocket, pois a URL versionada do script externo pode ter mudado.

Erros relacionados

- [Como corrigir o Delay JavaScript do WP Rocket que quebra funções do site](https://full.services/wp-fixer/corrigir-delay-javascript-wp-rocket/)
- [Como corrigir o erro de JavaScript ao combinar arquivos no WP Rocket](https://full.services/wp-fixer/corrigir-combinar-javascript-wp-rocket/)
- [Como corrigir o WP Rocket que não minifica o CSS](https://full.services/wp-fixer/corrigir-wp-rocket-nao-minifica-css/)

## Causa

- A opção 'Combine JavaScript Files' do WP Rocket agrupa o arquivo de terceiros no pacote concatenado e descarta a query string de versão original, fazendo o navegador requisitar uma URL que o servidor externo não reconhece.
- A opção 'Minify JavaScript Files' reescreve a URL do script externo servido por CDN, e a versão minificada perde o parametro ?ver= que o recurso de terceiros usa para servir o build correto.
- O arquivo externo problematico não esta listado no campo 'Excluded JavaScript Files' do WP Rocket, entao o plugin tenta otimiza-lo em vez de carrega-lo intacto como a doc oficial recomenda.
- A ordem de execução muda após a combinacao: um script de terceiros que dependia de carregar antes de uma biblioteca (como jQuery) passa a carregar depois no arquivo único, e a função dispara antes da dependencia existir.
- O recurso externo e servido por um domínio que respeita a query string como chave de cache; ao remover o parametro na otimização, o CDN do terceiro responde 404 ou entrega uma versão desatualizada.

## Como resolver

1. Identifique o script externo que quebrou no console: Abra a página afetada, pressione F12, va na aba Console e na aba Network e localize o arquivo de terceiros que falhou ao carregar. Anote a URL completa do .js externo, pois ela será usada na exclusão.

```
Abra a página no navegador e tecle F12
Va em Console e em Network e filtre por JS
Copie a URL completa do arquivo externo com erro (ex.: https://cdn.exemplo.com/widget.js)
```

2. Confirme a causa desligando a otimização de JavaScript: No painel do WP Rocket, na aba File Optimization, desative temporariamente 'Combine JavaScript Files' e 'Minify JavaScript Files', limpe o cache e recarregue a página. Se o script externo voltar a funcionar, a otimização de arquivos e a causa.

```
Painel WP -> Configurações -> WP Rocket -> aba File Optimization
Desmarque 'Combine JavaScript Files' e 'Minify JavaScript Files'
Clique em Save Changes e em Clear Cache
```

3. Exclua o arquivo externo da otimização: Em vez de deixar a otimização desligada para o site todo, reative 'Minify JavaScript Files' e adicione o script externo no campo 'Excluded JavaScript Files'. A documentação oficial do WP Rocket permite informar a URL completa ou apenas o domínio do recurso.

```
Painel WP -> WP Rocket -> File Optimization -> Excluded JavaScript Files
Cole a URL completa: https://cdn.exemplo.com/widget.js
Ou informe so o domínio: cdn.exemplo.com
Save Changes e Clear Cache
```

4. Trate dependencias de ordem com Delay ou Exclude: Se o erro for 'is not defined', o problema e ordem de carregamento. Mantenha o arquivo externo fora do Combine e, se usar 'Delay JavaScript Execution', adicione o script na lista de exclusão desse recurso para ele rodar na ordem original.

```
Painel WP -> WP Rocket -> File Optimization -> mantenha o arquivo fora do Combine
Em 'Delay JavaScript Execution', adicione o arquivo no campo de exclusão
Save Changes e Clear Cache
```

5. Valide em janela anonima e limpe os caches: Limpe o cache do WP Rocket, da CDN e do navegador e teste a página em uma janela anonima para descartar copia antiga. Confira o console novamente para garantir que o arquivo externo carrega sem erro.

```
Painel WP -> WP Rocket -> Dashboard -> Clear Cache
Limpe o cache da CDN e do navegador
Abra a página em janela anonima e reabra o Console (F12) para confirmar zero erro
```


## Código

```php
<?php
/**
 * Exclui scripts externos da otimizacao do WP Rocket via filtro,
 * versionando o controle no codigo em vez de so na interface.
 * Adicione ao functions.php do tema filho ou a um plugin proprio.
 */
add_filter( 'rocket_exclude_js', 'full_wp_rocket_excluir_scripts_externos' );
function full_wp_rocket_excluir_scripts_externos( $excluded ) {
    $excluded[] = '/wp-content/plugins/seu-widget/widget.js';
    return $excluded;
}

// Domínios de terceiros que o Minify/Combine nao deve tocar.
add_filter( 'rocket_minify_excluded_external_js', 'full_wp_rocket_dominios_externos' );
function full_wp_rocket_dominios_externos( $hosts ) {
    $hosts[] = 'cdn.exemplo.com';
    $hosts[] = 'widget.terceiro.com';
    return $hosts;
}
```

## Perguntas frequentes

### O WP Rocket tem uma opção para remover query strings dos arquivos estáticos

As versões atuais do WP Rocket não trazem mais um botão isolado para remover query strings, porque o Google deixou de recomendar essa prática. Na prática, o que altera as URLs versionadas hoje e a otimização de arquivos (Minify e Combine), e por isso que scripts externos podem quebrar.

### Por que um script externo parou de funcionar depois que ativei o WP Rocket

A otimização de JavaScript do WP Rocket combinou ou reescreveu a URL do arquivo de terceiros, descartando a query string de versão que ele precisa. O navegador entao falha ao carregar o recurso. A solução e excluir esse arquivo no campo 'Excluded JavaScript Files'.

### Como excluo um arquivo externo da otimização do WP Rocket

Na aba File Optimization, no campo 'Excluded JavaScript Files', informe a URL completa do arquivo ou apenas o domínio do serviço, conforme a documentação oficial. Depois salve as alterações e limpe o cache para o WP Rocket parar de otimizar aquele recurso.

### Posso usar so o domínio em vez da URL completa na exclusão

Sim. A documentação do WP Rocket aceita tanto a URL completa do arquivo quanto apenas o domínio no campo de exclusão. Usar o domínio cobre todos os arquivos servidos por aquele provedor, útil quando o serviço de terceiros carrega vários scripts.

### Devo desativar o Combine e o Minify do WP Rocket para resolver

Desativar serve so para confirmar a causa. Em seguida reative a otimização e exclua apenas o arquivo problematico, para não perder o ganho de performance no restante do site. Desligar tudo penaliza todas as páginas sem necessidade.

### O erro 'is not defined' tem a ver com query strings do WP Rocket

Esse erro costuma ser ordem de carregamento, não a query string em si. Ao combinar arquivos, o script externo pode carregar antes da dependencia. Mantenha o arquivo fora do Combine e exclua-o do Delay JavaScript Execution para preservar a ordem original.

### Como sei se o problema e do WP Rocket ou de outro plugin

Desative o WP Rocket, limpe o cache e teste a página. Se o script externo voltar, o plugin de cache e a causa. Reative o WP Rocket e va desligando uma opção da aba File Optimization por vez até isolar a configuração responsável.

**Fonte:** [WP Rocket Docs - Excluding External or Third-Party Content](https://docs.wp-rocket.me/article/39-excluding-external-or-third-party-content-from-cache/)