Tutorial de Python do Nodriver: Extração discreta de dados da Web — Do primeiro script à produção

• O Nodriver comunica diretamente com o CDP; por si só, não elimina riscos relacionados com IP, TLS ou comportamentais.
• Fixa a versão. Na versão 0.50.3 + Chrome 154 (2026-10-06), select retorna None em caso de falha, wait_for lança uma exceção e xpath falha com DOM.enable falta.
• Prefira uc.loop() em vez de asyncio.run para um encerramento correto; browser.stop() é sincronizado.
• Para trabalhos que exigem discrição, prefira o Chrome com interface gráfica sob o Xvfb: a versão sem interface gráfica ainda pode divulgar HeadlessChrome no UA.
• É na produção que os scrapers falham: contentores, concorrência limitada, novas tentativas, verificações do IP de saída, validação da saída.
• Mapeie esperas/ações para parâmetros da API do navegador (wait_for_css, wait_until, js_instructions, …) quando ultrapassar a capacidade de auto-hospedagem.

Percurso clássico do Selenium:

Your script  →  WebDriver protocol  →  chromedriver  →  Chrome

Percurso do Nodriver:

Your script  →  Chrome DevTools Protocol (websockets)  →  Chrome

Ignorar o binário do driver elimina os marcadores de automação específicos do WebDriver e toda uma classe de falhas relacionadas com discrepâncias de versão. Não torna o seu IP residencial, a sua pilha TLS única, nem o tempo dos seus cliques semelhante ao de um ser humano.

O Nodriver é o sucessor assíncrono e orientado para o CDP, proveniente da mesma linhagem de autores que o undetected-chromedriver. O modelo passa de «aplicar um patch ao driver» para «nunca utilizar o driver». Apenas para navegadores da família Chromium; API exclusivamente assíncrona.

Verificado por volta da preparação para publicação em 06/10/2026:

• Licença: AGPL-3.0 no pacote PyPI que instalámos. Isto é relevante para serviços ligados à rede que modificam e executam o código. Isto não constitui aconselhamento jurídico — peça a um advogado que leia a AGPL se fornecer um SaaS baseado num fork.
• Formato da API: apenas assíncrona; navegadores da família Chromium.
• Manutenção: a última versão do PyPI verificada para este guia é a 0.50.3 (13/05/2026). Verifique novamente as estrelas/issues/commits no dia da publicação antes de se comprometer com uma plataforma a longo prazo.
• Cobertura de testes / classificador alfa: o PyPI ainda indica «Estado de Desenvolvimento :: 3 - Alfa». Esteja preparado para possíveis falhas quando o Chrome mudar.
• Fork: existem o Zendriver e outros forks do CDP, caso necessite de uma abordagem de manutenção diferente — consulte a matriz de ferramentas mais adiante.

Precisa de suporte a vários navegadores (Firefox/WebKit), APIs de sincronização ou uma licença permissiva para um produto comercial sem análise da AGPL? O Nodriver pode não ser a base adequada.

python3 -m venv venv
source venv/bin/activate
pip install 'nodriver==0.50.3'

Lista de verificação de instalação:

1. Python ≥ 3.9.
2. Uma instalação local do Chrome/Chromium (confirme com google-chrome --version).
3. dependências de tempo de execução obtidas automaticamente: websockets>=14 , mss, deprecated.
4. Não nomeie o seu script nodriver.py (isso sobreporia o nome do pacote).
5. Teste: abre uma página pública e aguarda um seletor (script abaixo).

Ambiente de teste para este artigo: quotes.toscrape.com — um alvo de demonstração diferente da loja virtual utilizada em vários tutoriais concorrentes.

# 01_first_scraper.py — verified 2026-10-06 on nodriver 0.50.3
import nodriver as uc

async def main():
    browser = None
    try:
        browser = await uc.start(headless=True)
        tab = await browser.get("https://quotes.toscrape.com/")
        await tab.select("div.quote", timeout=15)  # wait for state, not time
        quotes = await tab.select_all("div.quote")
        for q in quotes:
            text_el = await q.query_selector("span.text")
            author_el = await q.query_selector("small.author")
            print((text_el.text or "").strip(), "—", (author_el.text or "").strip())
    finally:
        if browser is not None:
            browser.stop()  # sync on 0.50.3 — do not await

if __name__ == "__main__":
    # Package README recommends uc.loop(); see event-loop notes below
    uc.loop().run_until_complete(main())

def attr_get(el, name: str):
    if el is None:
        return None
    attrs = el.attrs  # ContraDict in nodriver 0.50.3
    if attrs is None:
        return None
    try:
        return attrs.get(name)
    except Exception:
        try:
            return attrs[name]
        except Exception:
            return None

# Observed: element.text and element.text_all both return usable strings

Falha no Chrome 154 + nodriver 0.50.3 (2026-10-06) ao chamar DOM.enable. Não distribua scrapers dependentes de XPath nesta combinação sem uma nova verificação.

Aguarde por um seletor, texto ou condição de rede inativa. Corrigido sleep destina-se a casos raros de depuração visual — não a scrapers finais. Prefira select / wait_for em vez de tab.sleep em percursos de produção.

Depois de clicar em «Seguinte», os identificadores dos elementos antigos podem desligar-se. Volte a consultar o controlo em cada tentativa; aguarde uma alteração do URL ou um novo seletor de conteúdo.

# Pagination retry pattern for quotes.toscrape.com-style next links
async def click_next_with_retry(tab, max_attempts=3) -> bool:
    for _ in range(max_attempts):
        next_link = await tab.select("li.next > a", timeout=5)
        if next_link is None:
            return False
        before = tab.url
        try:
            await next_link.click()
        except Exception:
            continue
        for _ in range(20):
            await tab.sleep(0.25)
            await tab.select("div.quote", timeout=2)
            if tab.url != before:
                return True
        if tab.url != before:
            return True
    return False

Páginas 1→2→3 avançadas; os autores alteraram-se conforme esperado.

Para páginas sem um controlo de link «Seguinte», percorra até uma condição de paragem: um marcador de fim, um limite de contagem ou o número máximo de iterações.

async def scroll_until_plateau(tab, max_rounds=20):
    history = []
    plateau = 0
    for round_i in range(1, max_rounds + 1):
        items = await tab.select_all("div.item")
        count = len(items)
        end = await tab.query_selector("#end-marker")
        history.append(count)
        if end is not None:
            return {"reason": "end_marker", "count": count}
        if len(history) >= 2 and history[-1] == history[-2]:
            plateau += 1
        else:
            plateau = 0
        if plateau >= 2:
            return {"reason": "count_plateau", "count": count}
        await tab.evaluate("window.scrollTo(0, document.body.scrollHeight)")
        await tab.sleep(0.4)
    return {"reason": "max_rounds", "count": history[-1] if history else 0}

Parou end_marker nos 40 itens após 4 rondas.

• Nova aba/janela: browser.get(url, new_tab=True) / new_window=True (API do pacote).
• tab.evaluate(expr) para sondagens de deslocamento/DOM — prefira seletores sempre que possível.
• Cookies: trate os jars como segredos; oculte-os nos registos (nota de segurança, não é um tutorial aprofundado sobre cookies).
• Capturas de ecrã: await tab.save_screenshot(...) funcionaram na nossa execução de diagnóstico.

Faz corresponder o agente do utilizador à versão do Chrome que realmente inicias. Uma rotação aleatória que não corresponda ao Chrome/154 (ou o que quer que esteja a executar) é um indício fácil de identificar. Dê preferência a uma identidade de ambiente de trabalho estável por cada perfil de trabalhador.

Apenas em páginas de diagnóstico públicas (bot.sannysoft.com; areyouheadless devolveu 502 em ambos os modos):

O 154.0.0.0 formulação dessas cadeias de caracteres é a forma reduzida do user-agent do Chrome, não um erro ortográfico em relação à 154.0.8037.57 . O Nodriver consegue limpar navigator.webdriver em ambos os modos, enquanto o modo «headless» continua a identificar-se através da cadeia de caracteres do agente de utilizador. Isso, por si só, é suficiente para muitas verificações simples.

Em servidores Linux sem ecrã físico:

# pattern
xvfb-run -a python your_scraper.py
# or export DISPLAY to a running Xvfb and start(headless=False)

Utilize o modo «headless» para sandboxes internas e CI. Utilize o modo «headed» + Xvfb quando o alvo identificar as cadeias de caracteres do agente de utilizador do modo «headless».

Não assuma que as configurações do Chrome correspondem às apresentadas noutros blogs. Antes de automatizar barreiras de login atrás de um proxy, verifique na sua versão do Chrome se o IP de saída do navegador é o IP do proxy — e não o IP do seu host.

# Guard pattern — wire to your proxy stack; always assert exit IP before scraping
async def assert_exit_ip(tab, expected_subnet_prefix: str | None = None):
    tab2 = await tab.browser.get("https://httpbin.org/ip")  # or your IP echo
    await tab2.select("body", timeout=15)
    body = (await tab2.get_content()) if hasattr(tab2, "get_content") else None
    # parse JSON IP; compare to expected proxy IP; fail closed
    return body

Cancele a tarefa se o IP de saída observado for o do seu host do centro de dados. Efetue esta verificação em produção, mesmo quando o proxy «parecer estar configurado».

Quando o problema for a reputação do IP ou a afinidade com o país — e não a automação do DOM —, encaminhe o tráfego através de proxies residenciais ou transfira o trabalho do navegador para um pedido da API do navegador com country definido.

A maioria dos tutoriais pára antes desta fase. É aqui que os scrapers falham.

# Outline only — adapt paths and package names for your base image
FROM python:3.13-slim-bookworm
RUN apt-get update && apt-get install -y --no-install-recommends \
    wget gnupg ca-certificates fonts-liberation xvfb \
    && install Google Chrome / Chromium per your distro docs \
    && useradd -m scraper
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
USER scraper
ENV DISPLAY=:99
CMD ["sh", "-c", "Xvfb :99 -screen 0 1920x1080x24 & python worker.py"]

Notas: execute como utilizador não-root; compreenda os sinalizadores da sandbox do Chrome em contentores restritos; mantenha os perfis num volume gravável se reutilizar cookies conquistados com esforço; e oculte esses cookies nos registos.

Concorrência limitada com um asyncio.Semaphore (ou trabalhadores em fila). Meça a memória por navegador em páginas semelhantes às de produção no seu hardware.

• Limite de tempo por navegação com wait_for / select limites.
• Classifique os erros: tempo limite, janela vazia, página de desafio, falha do Chrome.
• Reinicie o processo do navegador após erros de protocolo repetidos — não apenas o separador.
• Limitar as tentativas com backoff com jitter.

• Métricas: sucesso / bloqueio / tempo de espera / vazio por anfitrião.
• Captura de ecrã em caso de falha para armazenamento de objetos.
• Ocultação de registos: nome de utilizador/palavra-passe do proxy, Cookie cabeçalhos, dumps de armazenamento.

O «sucesso» de tipo HTTP no navegador não constitui HTML utilizável. Deteta títulos de desafio, estruturas de aplicações vazias e seletores obrigatórios em falta antes de gravar no armazém. Combina isto com a mentalidade de validação da tua stack de scraping mais ampla (evita ser bloqueado).

Âmbito (06/10/2026): apenas páginas públicas de impressão digital/diagnóstico. Sem alvos comerciais da Cloudflare ou da DataDome (de acordo com a política editorial deste artigo).

Considere qualquer afirmação do tipo «o nodriver contorna X» que não seja acompanhada de um teste datado e com âmbito definido como mera propaganda. Para alvos reforçados, consulte também as orientações do produto sobre como contornar o Cloudflare.

Versões verificadas através do índice PyPI em 06/10/2026. A postura de discrição é qualitativa, não uma pontuação.

Escolha com base nos seguintes critérios: licença, motor do navegador, necessidades de sincronização e quem é responsável pelo tempo de atividade.

• Problemas com ecrãs / Xvfb / GPU em máquinas virtuais na nuvem
• RAM e CPU por sessão simultânea do Chrome
• Proxies residenciais ou móveis
• Tempo de engenharia para atualizações do Chrome e seletores avariados
• Gestão de bloqueios e plantão
• Armazenamento de capturas de ecrã e ocultação de dados pessoais identificáveis
• Análise de conformidade com a AGPL

Opte pela auto-hospedagem quando precisar de sessões interativas prolongadas, extensões personalizadas ou integração estreita com redes internas. Adquira o serviço quando quiser livrar-se das responsabilidades relacionadas com SLAs de pedido/resposta, restrições geográficas e manutenção do navegador.

A API do navegador é uma chamada REST para https://api.webscrapingapi.com/v1—não um socket CDP ativo (confirmação do produto). Nomes dos parâmetros verificados nos parâmetros da API em 06/10/2026:

Documentação: Pedido GET, renderização em JavaScript.

Se precisar apenas de um instantâneo HTML renderizado sem um script de interação em várias etapas, comece com a API Scraper e a renderização em JS. Passe para a API do Navegador quando precisar de ações ordenadas, esperas de seletor, capturas de ecrã ou regras de extração numa única solicitação. Compare as opções em APIs de Acesso à Web.

A partir de erros que reproduzimos em 06/10/2026:

Extraia apenas páginas públicas elegíveis, respeite os robôs/Termos de Serviço e a legislação aplicável, minimize os dados pessoais e proteja as credenciais. Leia «Dados da Web responsáveis». Para um contexto «headless» mais abrangente, consulte «Navegador headless em Python».

Uma biblioteca Python assíncrona que controla o Chromium através do CDP sem o Selenium ou o chromedriver. Este guia utiliza a versão 0.50.3 (verificada em 06/10/2026).

O Selenium utiliza o WebDriver + um binário de driver. O undetected-chromedriver aplica patches a esse caminho. O nodriver ignora o WebDriver e comunica com o CDP de forma assíncrona.

Ele bloqueia alguns sinais de automação, mas não elimina fugas de IP, TLS, comportamento ou UA headless. Na nossa execução, navigator.webdriver foi False, mas o modo «headless» continuava exposto HeadlessChrome no UA.

Sim, para scraping funcional na nossa sandbox. Para alvos sensíveis à discrição, é preferível utilizar o modo «headed» + Xvfb, com base na diferença de UA que medimos.

Configure o proxy para a sua versão do Chrome e, em seguida, verifique sempre o IP de saída antes de iniciar a tarefa.

Não generalize a partir de páginas de diagnóstico para produtos de bots comerciais. Se utilizar verify_cf a versão 0.50.3, verifica-o nos teus próprios alvos antes de confiar nele.

Escolha com base na licença, no motor do navegador, nas necessidades de sincronização/assincronização e em quem é responsável pelas operações — consulte a matriz acima. O Playwright destaca-se no suporte a vários motores; o nodriver e o zendriver são otimizados para uma postura de discrição no CDP com a AGPL; a API do navegador hospedada é a melhor opção quando não pretende utilizar frotas do Chrome.

Instale o Chrome, execute em modo «headed» sob o Xvfb (ou aceite as desvantagens do modo «headless»), com um utilizador não root e workers limitados. Utilize o esboço do Dockerfile como ponto de partida e valide a imagem no seu ambiente.

Avalie com base no seu hardware e nas páginas de destino. Não confie em alegações de simultaneidade sem os seus próprios dados.

O pacote que instalámos está sob a licença AGPL-3.0. Consulte um advogado antes de o integrar num serviço de rede. Isto não constitui aconselhamento jurídico.

Quando pretender utilizar esperas/ações/localização geográfica REST sem ter de operar o Chrome, ou quando os custos de proxy e manutenção forem predominantes. Converta as suas esperas do nodriver em wait_for_css / js_instructions e compare uma solicitação.

Escolha uma página que o seu script do nodriver já processe e envie-a através de uma única solicitação da API do navegador com wait_for_css (e js_instructions se fizer scroll ou clicar). Compare o tempo de desenvolvimento, os modos de falha e o formato do resultado. Para grandes volumes, localização geográfica ou entrega gerida, contacte a equipa da WebScrapingAPI.