Corrigir problemas de JavaScript relacionados à Pesquisa | Central da Pesquisa Google | Documentation

Venha participar da nossa primeira conferência de SEO de três dias em Bangkok, de 23 a 25 de julho. Faça inscrição agora no Search Central Live Deep Dive 2025.

Este guia ajuda a identificar e corrigir problemas que podem impedir a exibição de uma página ou um conteúdo com JavaScript na Pesquisa Google. Embora a Pesquisa Google execute JavaScript, é preciso considerar algumas diferenças e limitações na criação de páginas e aplicativos para que os rastreadores possam acessar e renderizar o conteúdo. Nosso guia Princípios básicos de SEO em JavaScript tem mais informações sobre como é possível otimizar seu site JavaScript para a Pesquisa Google.

O Googlebot foi criado para se comportar bem na Web. Ele prioriza o rastreamento sem afetar a experiência dos usuários que acessam o site (link em inglês). O Googlebot e o componente Web Rendering Service (WRS) analisam e identificam continuamente recursos que não contribuem para o conteúdo essencial da página e podem não os buscar. Por exemplo, relatórios e solicitações de erros que não contribuem para o conteúdo essencial da página e outros tipos parecidos de solicitações que não são usadas ou são desnecessárias para extrair o conteúdo essencial da página. Talvez a análise do cliente não represente de maneira completa ou precisa as atividades do Googlebot e do WRS no site. Use o relatório de estatísticas de rastreamento no Google Search Console para monitorar a atividade e o feedback do Googlebot e do WRS no seu site.

Se você suspeitar que problemas de JavaScript estão impedindo a exibição de uma página ou um conteúdo com JavaScript na Pesquisa Google, siga estas etapas. Caso você não tenha certeza se o JavaScript é a causa principal, siga nosso guia geral de depuração para determinar o problema específico.

Para testar como o Google rastreia e renderiza um URL, use o teste de pesquisa aprimorada ou a Ferramenta de inspeção de URL no Search Console. É possível ver os recursos carregados, as saídas e as exceções do Console JavaScript, o DOM renderizado e outros dados.

Além disso, é recomendável coletar e auditar os erros de JavaScript encontrados no site pelos usuários, incluindo o Googlebot, para identificar problemas que possam afetar a renderização do conteúdo. Veja um exemplo que mostra como coletar erros de JavaScript registrados no gerenciador onerror global. Observação: alguns problemas de JavaScript, como erros de análise, não podem ser registrados com esse método.

window.addEventListener('error', function(e) {
    var errorText = [
        e.message,
        'URL: ' + e.filename,
        'Line: ' + e.lineno + ', Column: ' + e.colno,
        'Stack: ' + (e.error && e.error.stack || '(no stack trace)')
    ].join('\n');

    // Example: log errors as visual output into the host page.
    // Note: you probably don't want to show such errors to users, or
    //       have the errors get indexed by Googlebot; however, it may
    //       be a useful feature while actively debugging the page.
    var DOM_ID = 'rendering-debug-pre';
    if (!document.getElementById(DOM_ID)) {
        var log = document.createElement('pre');
        log.id = DOM_ID;
        log.style.whiteSpace = 'pre-wrap';
        log.textContent = errorText;
        if (!document.body) document.body = document.createElement('body');
        document.body.insertBefore(log, document.body.firstChild);
    } else {
        document.getElementById(DOM_ID).textContent += '\n\n' + errorText;
    }

    // Example: log the error to remote service.
    // Note: you can log errors to a remote service, to understand
    //       and monitor the types of errors encountered by regular users,
    //       Googlebot, and other crawlers.
    var client = new XMLHttpRequest();
    client.open('POST', 'https://example.com/logError');
    client.setRequestHeader('Content-Type', 'text/plain;charset=UTF-8');
    client.send(errorText);

});

Evite erros soft 404. Em um aplicativo de página única (SPA), isso pode ser particularmente difícil. Para evitar que páginas de erro sejam indexadas, você pode usar uma ou as duas estratégias a seguir:
- Redirecione para um URL em que o servidor responde com um código de status 404.
```
fetch(`https://api.kitten.club/cats/${id}`)
 .then(res => res.json())
 .then((cat) => {
   if (!cat.exists) {
     // redirect to page that gives a 404
     window.location.href = '/not-found';
   }
 });
```
- Adicione ou mude a tag meta robots para noindex.
```
fetch(`https://api.kitten.club/cats/${id}`)
 .then(res => res.json())
 .then((cat) => {
   if (!cat.exists) {
     const metaRobots = document.createElement('meta');
     metaRobots.name = 'robots';
     metaRobots.content = 'noindex';
     document.head.appendChild(metaRobots);
   }
 });
```
Quando um SPA usa o JavaScript do cliente para lidar com erros, ele geralmente informa um código de status HTTP 200 em vez do código de status correto. Isso pode levar à indexação de páginas de erro e, possivelmente, à exibição nos resultados de pesquisa.
O Googlebot recusa solicitações de permissão do usuário.
Os recursos que exigem permissão do usuário não fazem sentido para o Googlebot nem para todos os usuários. Por exemplo, se você tornar Camera API obrigatório, o Googlebot não vai poder fornecer uma câmera. Em vez disso, ofereça uma maneira de acessar o conteúdo sem forçar os usuários a permitir o acesso à câmera.
Não use fragmentos de URL para carregar conteúdos diferentes.
Um SPA talvez use fragmentos de URL (por exemplo, https://example.com/#/products) para carregar visualizações diferentes. O esquema de rastreamento AJAX foi descontinuado em 2015. Por isso, não espere que os fragmentos de URL funcionem com o Googlebot. Recomendamos usar a API History para carregar conteúdos diferentes com base no URL em um SPA.
Não dependa da persistência de dados para veicular conteúdo.
O WRS carrega cada URL (consulte Como a Pesquisa Google funciona para ter uma visão geral de como o Google descobre conteúdo), seguindo os redirecionamentos do servidor e do cliente, da mesma forma que um navegador comum. No entanto, o WRS não mantém o estado nos carregamentos de página:
- Os dados do armazenamento local e de sessão são apagados nos carregamentos de página.
- Os cookies de HTTP são apagados nos carregamentos de página.
Use a técnica de impressão digital de conteúdo para evitar problemas de cache com o Googlebot.
O Googlebot armazena muitos dados em cache para reduzir as solicitações de rede e o uso de recursos. O WRS pode ignorar cabeçalhos de armazenamento em cache. Talvez isso leve o WRS a usar recursos desatualizados de JavaScript ou CSS. A técnica de impressão digital de conteúdo evita esse problema ao criar uma referência à parte do nome do arquivo relativa ao conteúdo, como main.2bb85551.js. A impressão digital depende do conteúdo do documento. Por isso, cada atualização gera um nome de arquivo diferente. Veja o guia web.dev sobre estratégias de armazenamento em cache de longa duração para saber mais.
Verifique se o aplicativo usa a detecção de recursos para as principais APIs necessárias e oferece um comportamento substituto ou polyfill, quando aplicável.
Talvez alguns recursos da Web ainda não sejam usados por todos os user agents, e alguns deles podem desativar determinados recursos intencionalmente. Por exemplo, se você usar o WebGL para renderizar efeitos de foto no navegador, a detecção de recursos vai mostrar que o Googlebot não oferece suporte a WebGL. Para corrigir isso, você pode ignorar o efeito de foto ou fazer a renderização dele no servidor. Desse modo, seu conteúdo vai ser acessível a todos, incluindo o Googlebot.
Verifique se o conteúdo funciona com conexões HTTP.
O Googlebot usa solicitações HTTP para recuperar o conteúdo de servidores. Ele não é compatível com outros tipos de conexões, como WebSockets ou WebRTC. Para evitar problemas com essas conexões, forneça um substituto HTTP para buscar conteúdo e reforce o tratamento de erros e a detecção de recursos.
Verifique se os componentes da Web estão sendo renderizados como esperado. Use o teste de pesquisa aprimorada ou a Ferramenta de inspeção de URL para verificar se o HTML renderizado tem todo o conteúdo esperado.
O WRS nivela o light DOM e o shadow DOM. Se os componentes da Web usados não aplicarem o mecanismo <slot> para conteúdo light DOM, consulte a documentação do componente da Web para ver mais informações ou use outro componente. Para mais informações, consulte as práticas recomendadas para componentes da Web.
Após corrigir os itens nesta lista de verificação, teste sua página com o teste de pesquisa aprimorada ou a Ferramenta de inspeção de URL no Search Console novamente.
Quando o problema for corrigido, uma marca de seleção verde aparecerá e nenhum erro será exibido. Se o problema persistir, poste na Comunidade de Ajuda da Central da Pesquisa.