Como Resolver o Turnstile do Cloudflare ao Fazer Web Scraping

TL;DR:

• Cloudflare Turnstile pontua o navegador, não o usuário. Ele lê a consistência da impressora digital, sinais comportamentais e o IP de saída em segundo plano, então emite um cookie cf_clearance para um navegador que confia — então a solução é ser um navegador confiável, não responder a um enigma.
• Um navegador headless local falha no Turnstile em três eixos ao mesmo tempo: o aviso navigator.webdriver, a impressão digital padrão de headless e um IP de saída de datacenter. Corrigir os três manualmente é uma esteira de manutenção.
• O Scrapeless Scraping Browser limpa o Turnstile durante a renderização — um Chromium real auto-desenvolvido, uma impressão digital consistente por sessão e saída residencial em mais de 195 países, alcançada através de um único endpoint WebSocket.
• Seu código de automação permanece inalterado. Ele fala CDP, então puppeteer.connect() e chromium.connectOverCDP() funcionam como estão; você aponta a conexão para o navegador em nuvem e lê o DOM pós-desafio.
• Turnstile é enviado em três modos — não interativo, invisível e checkbox gerenciado — e todos os três terminam na mesma concessão cf_clearance em um navegador que passou.
• Gratuito para começar. Novas contas Scrapeless incluem tempo de execução gratuito do Scraping Browser — inscreva-se em app.scrapeless.com.

Introdução: Turnstile pontua o navegador, não um enigma

O Cloudflare Turnstile não é um CAPTCHA de imagem. Ele roda em segundo plano e avalia o navegador que carregou a página: se a impressão digital é internamente consistente, se os sinais de interação parecem humanos e se o IP de saída tem uma reputação limpa. Quando a pontuação é aprovada, o Cloudflare define um cookie cf_clearance e a página real carrega. Quando não, você recebe um intersticial em vez de conteúdo.

Isso muda o que "resolver o Turnstile" significa. Não há resposta a enviar — o trabalho é apresentar um navegador que o Cloudflare já confia. Um Chromium headless local não pode: ele anuncia automação através da propriedade navigator.webdriver, vem com fontes e comportamento de canvas padrão para headless, e sai de um IP que os serviços de reputação já conhecem. Você pode corrigir cada um deles localmente e, em seguida, continuar corrigindo à medida que o Chromium e os detectores mudam.

Este guia toma o caminho mais curto: dirija o Scrapeless Scraping Browser — um navegador em nuvem anti-detectável — com o Puppeteer ou Playwright que você já usa, para que a impressão digital, a superfície comportamental e o IP de saída sejam tratados no lado do servidor e o Turnstile seja limpo durante uma renderização normal.

O que o Turnstile realmente verifica

A documentação do Turnstile do Cloudflare descreve um widget que verifica os visitantes sem interrompê-los. Na prática, ele é enviado em três modos, e o mesmo navegador em nuvem lida com todos eles, porque apresenta um navegador real coerente em vez de um modificado:

Todos os três resolvem para um cookie cf_clearance — um padrão cookie HTTP — definido em um navegador que passou. O Turnstile também se baseia em tokens de estilo Privacy Pass definidos no protocolo de emissão Privacy Pass do IETF, que é o motivo pelo qual um navegador coerente e confiável importa mais do que qualquer única evasão.

Por que Scrapeless Scraping Browser

O Scrapeless Scraping Browser é um navegador em nuvem personalizável e anti-detectável, projetado para crawlers web e agentes de IA. Para o Turnstile especificamente, ele traz:

• Um Chromium real auto-desenvolvido que executa o JavaScript do widget exatamente como o Chrome, então o desafio é resolvido em vez de travar.
• Uma impressora digital consistente por sessão — sem aviso navigator.webdriver, sem desvios padrão de headless vazando.
• Saída residencial em mais de 195 países — o Turnstile avalia o IP de saída, e uma região residencial tem uma reputação limpa onde um IP de datacenter não tem.
• Persistência de sessão para que uma concessão cf_clearance possa ser reutilizada em solicitações na mesma sessão.
• Uma superfície de conexão — todas as opções são um parâmetro de consulta no mesmo endpoint WebSocket.

Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

Pré-requisitos

• Node.js 18 ou mais recente
• Uma conta Scrapeless e chave de API — inscreva-se em app.scrapeless.com
• Familiaridade básica com Puppeteer ou Playwright e o terminal

Os exemplos abaixo foram verificados em relação à superfície CDP documentada do Scraping Browser. Executá-los de ponta a ponta requer uma sessão Scrapeless ativa; adicione sua chave de API para executar cada um. Os detalhes de conexão completos estão na documentação do Scraping Browser.

Instalar

npm install puppeteer-core        # ou: playwright-core
export SCRAPELESS_API_KEY=sk_...   # chave gratuita em https://app.scrapeless.com

Configurar a conexão

Tudo é um parâmetro de consulta em wss://browser.scrapeless.com/api/v2/browser. Atribua proxyCountry a uma região residencial, uma vez que o Turnstile classifica o IP de saída.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.SCRAPELESS_API_KEY,
  sessionTTL: "180",
  proxyCountry: "US",
});
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://browser.scrapeless.com/api/v2/browser?${params}`,
});

Limpar o Turnstile e ler o token

O Scraping Browser do Scrapeless resolve o Turnstile automaticamente durante a renderização — não há chamada explícita para resolução a ser feita. Você navega e, em seguida, espera que o token do Turnstile apareça, que é o sinal de que o widget foi resolvido. A coleta subsequente fica a seu critério.

import puppeteer from "puppeteer-core";

const TARGET = "https://www.scrapingcourse.com/cloudflare-challenge";
const params = new URLSearchParams({
  token: process.env.SCRAPELESS_API_KEY,
  sessionTTL: "180",
  proxyCountry: "US",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://browser.scrapeless.com/api/v2/browser?${params}`,
});
const page = await browser.newPage();
await page.goto(TARGET, { waitUntil: "domcontentloaded", timeout: 60000 });

// O navegador resolve automaticamente o Turnstile; aguarde pelo token para confirmar que foi resolvido.
await page.waitForFunction(
  () => window.turnstile && window.turnstile.getResponse(),
  { timeout: 60000 }
);
const token = await page.evaluate(() => window.turnstile.getResponse());

console.log("token do turnstile ->", token.slice(0, 24) + "...");
console.log("título ->", await page.title());
await browser.close();

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

O mesmo fluxo no Playwright

O Playwright se conecta ao mesmo navegador de nuvem através do CDP; a sessão resolve automaticamente o Turnstile durante a renderização, e você aguarda o token da mesma forma.

import { chromium } from "playwright-core";

const params = new URLSearchParams({
  token: process.env.SCRAPELESS_API_KEY,
  sessionTTL: "180",
  proxyCountry: "US",
});
const browser = await chromium.connectOverCDP(
  `wss://browser.scrapeless.com/api/v2/browser?${params}`
);
const page = await browser.newPage();
await page.goto("https://www.scrapingcourse.com/cloudflare-challenge", {
  waitUntil: "domcontentloaded",
});
await page.waitForFunction(() => window.turnstile && window.turnstile.getResponse());
console.log("título ->", await page.title());
await browser.close();

Confirmar a passagem

O sinal confiável é o token do Turnstile — uma vez que window.turnstile.getResponse() retorna um valor, o widget foi resolvido e você pode prosseguir. O Cloudflare também define um cookie cf_clearance na sessão de aprovação, que você pode ler se precisar carregar a liberação para outras requisições.

const token = await page.evaluate(() => window.turnstile && window.turnstile.getResponse());
console.log("token do turnstile presente ->", Boolean(token));

const cookies = await page.cookies();
console.log("cf_clearance presente ->", cookies.some((c) => c.name === "cf_clearance"));

O que você recebe em troca

• O sinal navigator.webdriver está ausente — o navegador de nuvem não anuncia automação, portanto a primeira verificação que o Turnstile realiza parece um Chrome real.
• O IP de saída corresponde ao proxyCountry — uma região residencial é mais confiável do que um IP de data center, que o Turnstile classifica mal.
• O cf_clearance está presente após uma aprovação — reutilize a mesma sessão para transportar a autorização entre os pedidos subsequentes.
• Aqueça a sessão para páginas teimosas — carregue a homepage do site primeiro na mesma sessão antes da página protegida, para que a superfície comportamental pareça uma visita normal.

Conclusão: limpe o Turnstile, mantenha seu código

Resolver o Turnstile não se trata de responder a um desafio — trata-se de apresentar um navegador em que a Cloudflare confia. O Scrapeless Scraping Browser lida com as três coisas que o Turnstile pontua (impressão digital, comportamento, IP de saída) do lado do servidor, então seu código Puppeteer ou Playwright altera apenas a URL de conexão. Defina proxyCountry para uma região residencial, aqueça a sessão na página inicial e leia cf_clearance para confirmar a passagem. Para a diferença entre o intersticial e o widget, veja desafio Cloudflare vs Turnstile, e compare planos na página de preços da Scrapeless.

Pronto para Construir Seu Pipeline de Exclusão do Turnstile?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores que estão raspando sites protegidos pelo Turnstile: Discord · Telegram.

Inscreva-se em app.scrapeless.com para obter tempo de execução gratuito do Scraping Browser e aponte o Puppeteer ou Playwright para o navegador em nuvem que limpa o Turnstile durante a renderização.

Perguntas Frequentes

P: O Turnstile é um CAPTCHA que tenho que resolver com um serviço de resolução?
Não em um navegador que passa. O Turnstile, na maioria das vezes, pontua impressão digital, comportamento e IP em segundo plano e emite um cookie cf_clearance. O navegador em nuvem é projetado para passar nessa pontuação durante uma renderização normal, então não há um quebra-cabeça separado para responder.

P: Ele também lida com os modos invisíveis e não interativos?
Sim. Todos os três modos do Turnstile terminam na mesma concessão cf_clearance, e a sessão gerenciada lida com a pontuação passiva da mesma forma que lida com a variante de caixa de seleção.

P: Preciso de um proxy?
Não. A saída residencial é integrada — defina proxyCountry para uma região ou ANY. O Turnstile pontua o IP de saída, então uma região residencial libera de forma mais confiável do que um endereço de datacenter.

P: O desafio ainda aparece em algumas páginas — o que ajuda?
Defina proxyCountry para uma região residencial e aqueça a sessão carregando primeiro a página inicial do site na mesma sessão antes da página protegida, para que a superfície comportamental se assemelhe a uma visita normal.

P: Meu código Puppeteer ou Playwright é compatível?
Sim. O Scraping Browser fala CDP, então puppeteer.connect() e chromium.connectOverCDP() funcionam inalterados — você apenas muda a URL de conexão.

P: É legal limpar o Turnstile?
Acesse dados disponíveis publicamente de acordo com os termos do site e a legislação aplicável. Essas técnicas são para automação autorizada, testes e pesquisa onde você tem permissão.