# Como corrigir funcionalidades quebradas pelo Perfmatters

Funcionalidades quebradas pelo Perfmatters acontecem quando uma otimização do plugin remove ou atrasa um script ou estilo que a página precisava. As causas comuns são o Script Manager desativar um script necessário, o Delay JavaScript adiar o jQuery de um formulário ou slider, e o Remove Unused CSS cortar uma folha de estilo usada.

## O que é funcionalidades quebradas pelo Perfmatters?

Funcionalidades quebradas pelo Perfmatters significam que um recurso que funcionava (formulário que envia, slider que gira, menu mobile que abre, botão de checkout, mapa, popup) parou de responder depois que você ativou uma otimização no plugin. O Perfmatters acelera o site removendo ou adiando assets, e o problema surge quando ele remove ou adia justamente o asset de que aquela funcionalidade dependia. Não e um bug do plugin: e uma configuração agressiva demais para o seu site. Três recursos concentram a maioria dos casos: o Script Manager desliga scripts e folhas de estilo por página ou no site inteiro; o Delay JavaScript adia a execução do JS até a primeira interacao do visitante; e o Remove Unused CSS remove ou atrasa folhas de estilo consideradas não usadas. Em todos, basta o asset removido ou adiado ser o de que uma funcionalidade dependia para ela parar de operar.

## Como identificar

- Um formulário (Contact Form 7, WPForms, Gravity Forms) deixa de enviar e fica girando, ou o botão não responde ao clique.
- Um slider, carrossel, menu mobile ou popup para de abrir ou de animar depois que você ativou o Perfmatters.
- O console do navegador mostra a mensagem "Uncaught ReferenceError: jQuery is not defined" ou "$ is not a function".
- Um componente fica sem estilo (botão sem cor, grade desalinhada) após ligar o Remove Unused CSS.
- Com o Perfmatters em Testing Mode ou desativado pela barra de admin, a funcionalidade volta a operar normalmente.

**Antes de começar:** Antes de mexer no Script Manager ou no Remove Unused CSS, anote ou exporte as configurações atuais do Perfmatters em Perfmatters -> Tools -> Import/Export. Assim você consegue restaurar o estado anterior se uma excecao errada piorar o problema.

## Como prevenir

- Ative uma otimização agressiva por vez (Delay JavaScript, depois Remove Unused CSS) e teste as funcionalidades antes de ligar a próxima.
- Use sempre o Testing Mode para validar mudancas do Script Manager antes de aplicar para os visitantes.
- Mantenha o jQuery e os handles de formulários, sliders e pagamento na lista de excecao do Delay JavaScript desde o inicio.
- Após atualizar um plugin que você excluiu do Delay ou do Used CSS, revise se o nome do arquivo na excecao ainda corresponde a versão nova.
- Exporte as configurações do Perfmatters depois de cada ajuste validado, para ter um ponto de restauração confiavel.

Erros relacionados

- [Como corrigir scripts que não carregam pelo Script Manager do Perfmatters](https://full.services/wp-fixer/corrigir-script-manager-perfmatters/)
- [Como corrigir o conflito de JavaScript entre Perfmatters e Elementor](https://full.services/wp-fixer/corrigir-conflito-js-perfmatters-elementor/)
- [Como corrigir scripts essenciais do WooCommerce removidos pelo Perfmatters](https://full.services/wp-fixer/corrigir-scripts-woocommerce-perfmatters/)

## Causa

- No Script Manager, um script foi marcado como Disabled Everywhere sem excecao para a página que o usa, entao a funcionalidade quebra exatamente onde o script era necessário.
- O Delay JavaScript com a opção Delay all scripts adiou o jQuery, e os scripts de formulário, slider ou pagamento que dependem dele rodam antes da biblioteca carregar.
- O Remove Unused CSS removeu ou atrasou uma folha de estilo usada por um page builder pesado (Elementor, Divi), deixando o componente sem o CSS de que precisava.
- A opção Remove Query Strings retirou o parametro de versão (?ver=) de um script de terceiro hospedado fora, que so responde com a query string presente.
- A excecao de Delay ou de Used CSS aponta para um nome de arquivo que mudou de versão após uma atualização do plugin, entao a excecao deixou de casar e o asset voltou a ser adiado.
- O Disable WooCommerce Scripts/Styles foi ligado em um site que usa carrinho ou checkout, removendo os assets essenciais da loja fora das páginas de produto.

## Como resolver

1. Confirme que a culpa e do Perfmatters: abra a página quebrada, clique no item Perfmatters na barra de admin e ligue o Testing Mode (ou desative o plugin por um instante). Se a funcionalidade voltar, o problema e uma otimização do Perfmatters, não do tema ou de outro plugin.

```
Barra de admin -> Perfmatters -> Testing Mode (preview so para administradores)
```

2. Leia o console e identifique o asset: abra o console do navegador (F12) na página quebrada e anote a mensagem de erro. Um erro de jQuery is not defined aponta para o Delay JavaScript; um arquivo de script ou de CSS faltando aponta para o Script Manager ou para o Remove Unused CSS.

```
F12 -> aba Console (procure por "jQuery is not defined" ou "is not a function")
F12 -> aba Network (veja qual .js ou .css esperado não foi carregado)
```

3. Revise o Script Manager na página afetada: edite a página quebrada, abra o Script Manager pela barra de admin daquela URL e confira se algum script da funcionalidade esta como Disabled. Reative ou abra uma excecao de Current URL para o script desligado Everywhere.

```
Editar a página -> barra de admin -> Script Manager
Localize o script -> Status: On (ou em Disabled Everywhere, marque Current URL como excecao)
Salve e recarregue a página sem cache
```

4. Adicione excecoes no Delay JavaScript: em Perfmatters -> Assets -> JavaScript, na área de Delay JavaScript, inclua na lista de excecao o jQuery e o handle do script da funcionalidade que quebrou. Excluir o jQuery preserva a ordem de carregamento dos scripts que dependem dele.

```
Perfmatters -> Assets -> JavaScript -> Delay JavaScript -> Exclude Scripts
jquery
jquery-core
jquery-migrate
```

5. Trate o Remove Unused CSS sem cortar o estilo usado: em Perfmatters -> Assets -> CSS, troque o método de Stylesheet Behavior de Remove para Delay (default), que adia em vez de remover, e adicione na excecao a folha de estilo ou o seletor do componente sem estilo. Depois limpe o Used CSS para regenerar.

```
Perfmatters -> Assets -> CSS -> Remove Unused CSS -> Stylesheet Behavior: Delay
Used CSS -> Excluded Stylesheets (informe o nome do arquivo .css)
Used CSS -> Excluded Selectors (informe a classe ou id do componente)
Tools -> Clear Used CSS
```

6. Limpe o cache e valide em janela anonima: limpe o cache do Perfmatters e do seu plugin de cache, desligue o Testing Mode e teste a funcionalidade numa janela anonima. Confirme que o recurso voltou para o visitante, não so para você logado como administrador.

```
Perfmatters -> Tools -> Clear Cache
Teste em janela anonima (Ctrl+Shift+N) com o Testing Mode desligado
```


## Código

```php
// functions.php do tema-filho: reforca o jQuery para qualquer script que dependa dele,
// caso o Delay JavaScript do Perfmatters ainda adie a biblioteca em alguma pagina.
// Isso registra o jQuery do core como dependencia explicita, sem desligar o plugin.
add_action( 'wp_enqueue_scripts', function () {
    // garante que o jQuery do WordPress carregue antes dos scripts da pagina
    if ( ! is_admin() ) {
        wp_enqueue_script( 'jquery' );
    }
}, 1 );

// Filtro do proprio Perfmatters: forca exclusao do jQuery do Delay JavaScript via codigo,
// util quando a UI nao casa o handle correto apos uma atualizacao.
add_filter( 'perfmatters_delay_js_exclusions', function ( $exclusions ) {
    $exclusions[] = 'jquery.min.js';
    $exclusions[] = 'jquery-migrate.min.js';
    return $exclusions;
} );
```

## Perguntas frequentes

### Por que o Perfmatters quebrou meu formulário de contato?

Quase sempre porque o Delay JavaScript adiou o jQuery ou o script do formulário, ou porque o Script Manager desativou esse script na página. Adicione jquery e o handle do formulário na excecao do Delay JavaScript, ou reative o script no Script Manager daquela URL, e o envio volta a funcionar.

### Como descubro qual opção do Perfmatters quebrou a funcionalidade?

Ligue o Testing Mode pela barra de admin: se o recurso voltar, a causa e o Perfmatters. Depois abra o console do navegador na página afetada. Um erro de jQuery aponta para o Delay JavaScript, e um arquivo de script ou CSS faltando aponta para o Script Manager ou o Remove Unused CSS.

### O que e o erro jQuery is not defined depois de ativar o Perfmatters?

E o sinal de que o jQuery foi adiado pelo Delay JavaScript, mas um script que depende dele rodou antes da biblioteca carregar. A correção e excluir jquery, jquery-core e jquery-migrate da lista de Delay JavaScript, preservando a ordem original de carregamento.

### Preciso desativar o Perfmatters inteiro para corrigir?

Não. O ideal e isolar a opção culpada com o Testing Mode e o console, e abrir apenas a excecao necessaria no Script Manager, no Delay JavaScript ou no Remove Unused CSS. Desligar tudo so confirma o diagnostico; você mantem o ganho de velocidade ajustando uma opção por vez.

### Por que o layout ficou sem estilo após ligar o Remove Unused CSS?

Porque o recurso removeu ou atrasou uma folha de estilo que a página usava. Troque o Stylesheet Behavior de Remove para Delay, adicione o arquivo .css ou o seletor do componente nas excecoes de Used CSS e clique em Clear Used CSS para regenerar o estilo correto.

### O problema aparece para mim mas não para os visitantes (ou o contrario). Por que?

Otimizacoes do Perfmatters como o Delay JavaScript so atuam para visitantes não logados, e o Testing Mode mostra a versão otimizada so para o administrador. Por isso o teste final tem de ser numa janela anonima com o Testing Mode desligado, para reproduzir exatamente o que o visitante recebe.

### Como evito que uma atualização de plugin quebre a funcionalidade de novo?

Excecoes de Delay e de Used CSS apontam para nomes de arquivo, e uma atualização pode mudar a versão do arquivo. Depois de atualizar um plugin excluido, confira se o nome na excecao ainda corresponde, e mantenha um export das configurações do Perfmatters como ponto de restauração.

### O Disable WooCommerce Scripts do Perfmatters pode quebrar minha loja?

Pode, se a loja usa carrinho ou checkout em páginas além das de produto. Essa opção remove os assets do WooCommerce onde ele acha que não são usados. Use o Script Manager para reativar os scripts do WooCommerce nas páginas de carrinho, checkout e minha conta, ou desligue a opção se a loja depende deles em todo o site.

**Fonte:** [Perfmatters — Script Manager (disable scripts per post/page)](https://perfmatters.io/docs/disable-scripts-per-post-page/)