rebrowser/rebrowser-patchesColeção de patches para puppeteer e playwright visando evitar detecção de automação e vazamentos. Ajuda a evitar páginas de CAPTCHA do Cloudflare e DataDome. Fácil de aplicar/remover o patch, podendo ser habilitado/desabilitado sob demanda.
Este repositório contém patches para aprimorar bibliotecas populares de automação web. Especificamente, ele tem como alvo os pacotes puppeteer e playwright.
Alguns aspectos das bibliotecas de automação ou do comportamento do navegador não podem ser ajustados por meio de configurações ou opções de linha de comando. Portanto, corrigimos esses problemas aplicando patches no código-fonte da biblioteca. Embora essa abordagem seja frágil e possa quebrar à medida que o código-fonte das bibliotecas muda ao longo do tempo, o objetivo é manter este repositório com a ajuda da comunidade para manter os patches atualizados.
Prontos para uso, o Puppeteer e o Playwright vêm com alguns vazamentos significativos que são fáceis de detectar. Não importa quão bons sejam seus proxies, impressões digitais e scripts de comportamento: se você não tiver o patch aplicado, você é apenas uma grande bandeira vermelha para qualquer site importante.
🕵️ Você pode facilmente testar sua configuração de automação contra as principais detecções modernas com o rebrowser-bot-detector (fontes e detalhes)
| Antes dos patches 👎 | Depois dos patches 👍 |
|---|---|
 |  |
Se você não quer lidar com os patches e todos os possíveis erros, existe uma solução de substituição direta para você. Esses pacotes simplesmente aplicaram o rebrowser-patches sobre o código original, nada mais.
Puppeteer: rebrowser-puppeteer (src) e rebrowser-puppeteer-core (src)
Playwright (Node.js): rebrowser-playwright (src) e rebrowser-playwright-core (src)
Playwright (Python): rebrowser-playwright (src)
A maneira mais fácil de começar a usá-lo é ajustar seu package.json para usar os novos pacotes, mas manter o nome antigo como um alias. Dessa forma, você não precisa alterar nenhum código-fonte da sua automação. Veja como fazer isso:
package.json e substitua "puppeteer": "^23.3.1" e "puppeteer-core": "^23.3.1" por "puppeteer": "npm:rebrowser-puppeteer@^23.3.1" e "puppeteer-core": "npm:rebrowser-puppeteer-core@^23.3.1". Nota: 23.3.1 é apenas um exemplo; verifique a versão mais recente no npm.npm install (ou yarn install)Outra maneira é usar de fato os novos pacotes em vez do original. Aqui estão os passos que você precisa seguir:
package.json e substitua os pacotes puppeteer e puppeteer-core por rebrowser-puppeteer e rebrowser-puppeteer-core. Não altere as versões dos pacotes, apenas substitua os nomes.npm install (ou yarn install)puppeteer e puppeteer-core por rebrowser-puppeteer e rebrowser-puppeteer-core🚀 É isso! Basta visitar a página do rebrowser-bot-detector e testar seu navegador com patch aplicado.
Nosso objetivo é manter e dar suporte a esses pacotes de substituição direta com as versões mais recentes, mas focamos principalmente em versões novas. Então, se você ainda está usando o puppeteer 13.3.7 do início dos anos 90, talvez seja uma boa hora para atualizar. Há uma grande chance de que nada quebre, pois a API é bastante estável ao longo do tempo.
Runtime.EnableBibliotecas populares de automação dependem do comando CDP Runtime.Enable, que permite receber eventos do domínio Runtime.. Isso é crucial para gerenciar os contextos de execução usados para avaliar JavaScript nas páginas, um recurso essencial para qualquer processo de automação.
No entanto, existe uma técnica que detecta o uso desse comando, revelando que o navegador está sendo controlado por software de automação como Puppeteer ou Playwright. Essa técnica é usada por todos os principais softwares anti-bot, como Cloudflare, DataDome e outros.
Preparamos um artigo completo sobre nossa investigação desse vazamento, que você pode ler em nosso blog.
Para mais detalhes sobre essa técnica, leia a publicação do blog da DataDome: How New Headless Chrome & the CDP Signal Are Impacting Bot Detection.
Em resumo, são algumas linhas de JavaScript na página que são chamadas automaticamente se Runtime.Enable foi usado.
Nossa correção desativa o comando automático Runtime.Enable em cada frame. Em vez disso, criamos manualmente contextos com IDs desconhecidos quando um frame é criado. Então, quando o código precisa ser executado, há várias maneiras de obter o ID do contexto.
🟢 Prós: A abordagem definitiva que mantém o acesso ao mundo principal e funciona com web workers e iframes. Você não precisa alterar nenhuma parte do seu código existente.
🔴 Contras: Nenhum descoberto até agora.
Page.createIsolatedWorld e salvar seu ID.🟢 Prós: Todo o seu código será executado em um mundo isolado separado, impedindo que os scripts da página detectem suas alterações via MutationObserver e outras técnicas.
🔴 Contras: Você não poderá acessar variáveis e código do contexto principal. Embora isso seja necessário para alguns casos de uso, o contexto isolado geralmente funciona bem para a maioria dos cenários. Além disso, web workers não permitem criar novos mundos, então você não pode executar seu código dentro de um worker. Esse é um caso de uso específico, mas pode ser importante em algumas situações. Existe uma solução alternativa para esse problema; leia How to Access Main Context Objects from Isolated Context in Puppeteer & Playwright.
Runtime.Enable e depois imediatamente chamar Runtime.Disable.Isso dispara eventos Runtime.executionContextCreated, permitindo capturar o ID de contexto correto.
🟢 Prós: Você terá acesso total ao contexto principal.
🔴 Contras: Há uma pequena chance de que, durante esse curto intervalo de tempo, a página chame código que leve ao vazamento. O risco é baixo, pois o código de detecção geralmente é chamado durante ações específicas, como páginas de CAPTCHA ou formulários de login/registro, normalmente logo após o carregamento da página. Sua lógica de negócios geralmente é chamada um pouco depois.
🎉 Nossos testes mostram que todas essas abordagens são atualmente indetectáveis pelo Cloudflare ou DataDome.
Nota: você pode alterar as configurações deste patch em tempo real usando uma variável de ambiente. Isso permite alternar facilmente entre versões com e sem patch com base na sua lógica de negócios.
REBROWSER_PATCHES_RUNTIME_FIX_MODE=addBinding — técnica addBinding (padrão)REBROWSER_PATCHES_RUNTIME_FIX_MODE=alwaysIsolated — sempre executar todos os scripts em contexto isoladoREBROWSER_PATCHES_RUNTIME_FIX_MODE=enableDisable — usar a técnica Enable/DisableREBROWSER_PATCHES_RUNTIME_FIX_MODE=0 — desativar completamente a correção para este vazamentoREBROWSER_PATCHES_DEBUG=1 — ativar algumas mensagens de depuraçãoLembre-se de que você pode definir essas variáveis de diferentes maneiras, por exemplo, no código:
process.env.REBROWSER_PATCHES_RUNTIME_FIX_MODE = "alwaysIsolated"
ou na linha de comando:
REBROWSER_PATCHES_RUNTIME_FIX_MODE=alwaysIsolated node app.js
Por padrão, o Puppeteer adiciona //# sourceURL=pptr:... a cada script em page.evaluate(). Um site remoto pode detectar esse comportamento e levantar bandeiras vermelhas.
Este patch o altera para //# sourceURL=app.js. Você também pode ajustá-lo por meio de uma variável de ambiente:
# use any generic filename
REBROWSER_PATCHES_SOURCE_URL=jquery.min.js
# use 0 to completely disable this patch
REBROWSER_PATCHES_SOURCE_URL=0
Às vezes, pode ser muito útil acessar uma sessão CDP no nível do navegador. Por exemplo, quando você deseja implementar algum comando CDP personalizado. Existe um método page._client() que retorna a sessão CDP para a instância atual da página, mas não existe esse método para a instância do navegador.
Este patch adiciona um novo método _connection() à classe Browser, para que você possa usá-lo assim:
browser._connection().on('Rebrowser.addRunEvent', (params) => { ... })
Nota: não é detectável por scripts externos do site, é apenas para sua conveniência.
O nome padrão do utility world é '__puppeteer_utility_world__' + packageVersion. Às vezes, você pode querer alterá-lo para outra coisa. Este patch o altera para util e permite personalizá-lo por meio de uma variável de ambiente:
REBROWSER_PATCHES_UTILITY_WORLD_NAME=customUtilityWorld
# use 0 to completely disable this patch
REBROWSER_PATCHES_UTILITY_WORLD_NAME=0
Esta variável de ambiente não pode ser alterada em tempo real; você precisa defini-la antes de executar seu script, pois ela é usada no momento em que o módulo é importado.
| Antes do patch 👎 | Depois do patch 👍 |
|---|---|
 |
Nota: não é detectável por scripts externos do site, mas o Google pode usar essas informações no Chrome proprietário deles; nunca sabemos.
Este pacote foi projetado para ser executado contra uma biblioteca instalada. Instale a biblioteca, chame o patcher e está pronto para usar.
Na pasta raiz do seu projeto, execute:
npx rebrowser-patches@latest patch --packageName puppeteer-core
Você pode reverter facilmente todas as alterações com este comando:
npx rebrowser-patches@latest unpatch --packageName puppeteer-core
Você também pode aplicar o patch a um pacote fornecendo o caminho completo para sua pasta, por exemplo:
npx rebrowser-patches@latest patch --packagePath /web/app/node_modules/puppeteer-core-custom
Você pode ver todas as opções de linha de comando executando npx rebrowser-patches@latest --help, mas atualmente há apenas um patch para uma biblioteca, então você não precisa configurar nada.
⚠️ Esteja ciente de que, após executar npm install ou yarn install na pasta do seu projeto, isso pode sobrescrever todas as alterações dos patches. Você precisará executar o patcher novamente para manter os patches aplicados.
Se você já tem seu pacote com patch aplicado e deseja atualizar para a versão mais recente do rebrowser-patches, a maneira mais fácil seria excluir node_modules/puppeteer-core, depois executar npm install ou yarn install --check-files e, em seguida, executar npx rebrowser-patches@latest patch.
Todas essas versões são apenas wrappers em torno da versão Node.js do Playwright. Você precisa encontrar a pasta driver dentro do seu pacote Playwright e executar este patch com --packagePath=$yourDriverFolder/$yourPlatform/package.
✅ Versão mais recente totalmente testada: 24.8.1 (lançada em 2025-05-06)
Os patches do Playwright incluem:
Runtime.enable: modos addBinding e alwaysIsolated.REBROWSER_PATCHES_UTILITY_WORLD_NAME.Importante: o método page.pause() não funciona com a correção habilitada; ele precisa de mais investigação. Você pode simplesmente desativar completamente a correção durante a depuração usando a variável de ambiente REBROWSER_PATCHES_RUNTIME_FIX_MODE=0.
Estes patches funcionam apenas no Chrome por enquanto. Se você realmente quiser usá-lo com WebKit ou Firefox, abra uma nova issue.
✅ Versão mais recente totalmente testada: 1.52.0 (lançada em 2025-04-17)
rebrowser-puppeteer com o puppeteer-extra?Use o método addExtra, aqui está o exemplo:
// before
import puppeteer from 'puppeteer-extra'
// after
import { addExtra } from 'puppeteer-extra'
import rebrowserPuppeteer from 'rebrowser-puppeteer-core'
const puppeteer = addExtra(rebrowserPuppeteer)
Atualmente, estamos desenvolvendo mais patches para melhorar a transparência da automação web, que serão lançados neste repositório em breve. Por favor, apoie o projeto clicando no botão ⭐️ star ou watch.
💭 Se você tiver ideias, pensamentos ou perguntas, sinta-se à vontade para entrar em contato com nossa equipe por email ou usar a seção de issues.
⚠️ É importante saber que essa correção sozinha não tornará seu navegador à prova de balas e indetectável. Você precisa lidar com muitos outros aspectos, como proxies, user-agent adequado e impressões digitais (canvas, WebGL), entre outros.
Tenha sempre em mente: quanto menos você manipular as partes internas do navegador por meio de injeções de JS, melhor. Existem maneiras de detectar que objetos internos como console, navigator e outros foram afetados por objetos Proxy ou Object.defineProperty. É complicado, mas é sempre um jogo de gato e rato.
Se você já tentou de tudo e ainda enfrenta problemas, tente fazer uma pergunta na seção de issues ou considere usar as soluções em nuvem da Rebrowser.
Este pacote é patrocinado e mantido pela Rebrowser. Nós permitimos que você dimensione sua automação de navegador e web scraping na nuvem com centenas de impressões digitais únicas.
Nossos navegadores em nuvem têm ótimas taxas de sucesso e vêm com recursos interessantes, como notificações se sua biblioteca usa Runtime.Enable durante a execução ou se tem outras bandeiras vermelhas que podem ser melhoradas. Crie uma conta hoje para ser convidado a testar nossa plataforma de ponta e leve seu negócio de automação para o próximo nível.
Ao tentar executar este patcher em uma máquina Windows, você provavelmente encontrará um erro porque o comando patch não é encontrado. Para corrigir isso, você precisa instalar o Git, que inclui o patch.exe. Depois de instalá-lo, você precisa adicioná-lo ao seu PATH:
set PATH=%PATH%;C:\Program Files\Git\usr\bin\
Você pode verificar se o patch.exe está instalado corretamente usando o seguinte comando:
patch -v
zfcsoftware/puppeteer-real-browser - ideias gerais e contribuição para a comunidade de automação
Kaliiiiiiiiii-Vinyzu/patchright - conjunto de patches para corrigir vazamentos do Playwright
kaliiiiiiiiii/brotector - alguns testes modernos, algoritmo para distinguir CDP vs devtools
prescience-data/harden-puppeteer - um dos pioneiros da execução em um mundo isolado
puppeteer-extra-plugin-stealth - onde tudo começou, muitos créditos a todos os contribuidores e à comunidade 🙏 berstend e cia. são os maiores