# Configurazione Proxy Patchright: Avvio, Contesti, Autenticazione e Docker

Patchright corregge le perdite del CDP che espongono Playwright prima che il browser inizi. Non tocca la reputazione del tuo IP — e la sua configurazione stealth raccomandata cambia silenziosamente il modo in cui ruoti i proxy.

Patchright è una versione patchata e non rilevata di Playwright che funziona come sostituto diretto: cambia l'importazione, mantieni il codice. Le patch vengono applicate **prima che il processo del browser inizi** — rimuovono i flag di automazione e le chiamate del Chrome DevTools Protocol che permettono a un sito di identificare una sessione Playwright nei suoi primi millisecondi. Ciò che non toccano è la rete. Ogni domanda sui proxy Patchright ritorna a quella divisione, e a un dettaglio che il README nasconde: la configurazione che il progetto raccomanda per la massima discrezione è un contesto persistente, che cambia silenziosamente il modo in cui ruoti le uscite. Questa è la guida focalizzata sui proxy — avvio contro contesto, gateway autenticati, Docker e un resoconto onesto del limite.

## Installazione e il proxy diretto

Patchright è disponibile per Python, Node e .NET, e applica patch solo a Chromium — Firefox e WebKit non sono supportati esplicitamente. Installalo e scarica il vero Google Chrome piuttosto che il Chromium incluso, che il progetto raccomanda per discrezione:

```bash
pip install patchright
patchright install chrome
# Node: npm i patchright && npx patchright install chrome
```

L'API del proxy è quella di Playwright, invariata, perché i proxy sono una delle poche cose che Patchright lascia deliberatamente intatte. Le credenziali vanno in campi dedicati, mai all'interno dell'URL del server — motivo per cui i proxy autenticati non necessitano di un'estensione qui, a differenza di Selenium o Puppeteer grezzo:

```python
from patchright.sync_api import sync_playwright

PROXY = {
    "server": "http://residentialpremium.quantumproxies.io:8080",
    "username": "USER",
    "password": "PASS",
}

with sync_playwright() as p:
    browser = p.chromium.launch(channel="chrome", proxy=PROXY)
    page = browser.new_page()
    page.goto("https://httpbin.org/ip")
    print(page.text_content("body"))   # the exit IP
    browser.close()
```

Questa è l'intera risposta alla domanda "Patchright supporta i proxy": sì, identicamente a Playwright a monte, inclusa la lista `bypass` e la particolarità di Chromium che gli indirizzi loopback saltano completamente il proxy — quindi testare contro un server mock locale sembrerà sempre che il proxy venga ignorato. Se sei nuovo al modello sottostante, la nostra [guida all'integrazione del proxy Playwright](https://quantumproxies.io/blog/playwright-proxy-integration) copre il comportamento di base, e la [mappa dei proxy dei framework anti-detect](https://quantumproxies.io/blog/anti-detect-frameworks-authenticated-proxies-map) confronta quali stack accettano le credenziali nativamente.

## Proxy per contesto e stub globale

I contesti sono l'unità di rotazione economica: cookie, storage e cache separati, creati in millisecondi invece dei secondi che costa lanciare un browser. Ognuno prende la propria opzione `proxy`, quindi un singolo processo può mantenere un'identità statunitense e una tedesca contemporaneamente. C'è un problema documentato di Playwright che inganna le persone qui — il browser deve essere lanciato con un proxy globale affinché i proxy per contesto funzionino su Chromium. Se ogni contesto lo sovrascrive, il valore globale non viene mai usato e può essere qualsiasi stringa segnaposto:

```js
const { chromium } = require('patchright');

(async () => {
  // the global proxy is never used — it only enables the per-context option
  const browser = await chromium.launch({
    channel: 'chrome',
    proxy: { server: 'http://per-context' },
  });

  for (const job of jobs) {
    const context = await browser.newContext({
      proxy: {
        server: 'http://residentialpremium.quantumproxies.io:8080',
        username: 'USER-country-' + job.country,   // geo in the username
        password: 'PASS',
      },
    });
    const page = await context.newPage();
    try {
      await page.goto(job.url, { timeout: 30000 });
      // ...extract...
    } finally {
      await context.close();   // burns the cookies with the exit
    }
  }
  await browser.close();
})();
```

Puntato a un gateway rotante, ogni contesto esce da un indirizzo diverso in un pool residenziale di oltre 90 milioni senza gestione delle liste da parte tua — questo è ciò che i [proxy rotanti](https://quantumproxies.io/rotating-proxies) fanno lato server. Nota dove risiedono i controlli geo e di sessione in quel frammento: nel nome utente, non in un'intestazione personalizzata. Questo conta di più in Patchright che in Playwright semplice, perché la guida del progetto stesso è di evitare intestazioni personalizzate e sovrascritture dell'user-agent, poiché i valori iniettati sono essi stessi una superficie di rilevamento. Il controllo dei parametri del nome utente mantiene intatta la forma della richiesta del browser.

![Due modi di usare i proxy in Patchright: avviare il browser e dare a ogni contesto il proprio proxy per una rotazione rapida, oppure usare il contesto persistente che il progetto consiglia per la stealth, che ha esattamente un contesto e quindi un'uscita per processo. La scheda segnala lo stub di proxy globale necessario per avere proxy per contesto.](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785776555/blog/generated/qp-b10-009-diag1.png)
*Il compromesso che nessuno dichiara: la rotazione veloce vive nei contesti, la massima discrezione vive in un profilo persistente — e un profilo persistente ha esattamente un contesto.*

## Il compromesso del contesto persistente

La configurazione stealth raccomandata da Patchright non è `launch()`. È `launch_persistent_context()` con un vero canale Chrome, una directory dei dati utente, nessuna sovrascrittura del viewport e modalità con interfaccia grafica — e esplicitamente senza intestazioni personalizzate o un user agent falsificato. Quella configurazione persiste anche qualsiasi cookie di autorizzazione che una sfida ti consegna, quindi una sfida risolta è riutilizzabile tra le esecuzioni. La conseguenza del proxy è strutturale: un contesto persistente *è* il contesto. Non c'è `newContext()` su cui appendere un secondo proxy, quindi un processo equivale a un'identità di uscita.

```python
from patchright.sync_api import sync_playwright

with sync_playwright() as p:
    ctx = p.chromium.launch_persistent_context(
        user_data_dir="profiles/it-01",   # one profile per identity
        channel="chrome",
        headless=False,
        no_viewport=True,
        proxy={
            "server": "http://residentialpremium.quantumproxies.io:8080",
            "username": "USER-country-it-sid-it01-ttl-30m",   # sticky, pinned to the profile
            "password": "PASS",
        },
        # do NOT pass user_agent or extra_http_headers here
    )
    page = ctx.new_page()
    page.goto("https://example.com")
    ctx.close()
```

Quindi la rotazione diventa una decisione a livello di processo: una directory di profilo per identità, una sessione fissa associata ad essa, e un pool di lavoratori invece di un ciclo di contesto. Mantieni stabile l'abbinamento — un profilo che ha accumulato cookie dietro un'uscita italiana e poi riappare dietro una brasiliana è una contraddizione che nessuna patch CDP può nascondere. Regola pratica: nomina la directory dopo l'id della sessione, elimina la directory quando bruci la sessione, e non condividere mai un profilo tra due uscite.

## Esecuzione di Patchright in Docker dietro un proxy

Containerizzare un browser stealth ha due trappole, e entrambe hanno conseguenze sui proxy. La prima è `--no-sandbox`: la solita correzione per Chrome che si rifiuta di avviarsi come root, e un flag che i venditori anti-bot leggono felicemente. Esegui come utente non root invece. La seconda è la modalità headless — il progetto raccomanda con interfaccia grafica, quindi usa un display virtuale piuttosto che ricorrere all'interruttore headless:

```bash
# Dockerfile
FROM python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
      xvfb ca-certificates && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir patchright \
 && patchright install --with-deps chrome

RUN useradd -m app
USER app
WORKDIR /home/app
COPY --chown=app:app scrape.py .

# headed under a virtual display: no --no-sandbox, no HeadlessChrome tell
CMD ["xvfb-run", "-a", "python", "scrape.py"]

# build & run:
#   docker build -t patchright-worker .
#   docker run --ipc=host --shm-size=1g patchright-worker
```

Le opzioni `--ipc=host` e un più grande `/dev/shm` sono le correzioni standard per Chromium-in-Docker per i crash delle schede sotto carico, direttamente dai documenti del container Playwright. Una trappola specifica per i proxy: se esegui un relay locale per aggiungere credenziali a un endpoint SOCKS5, `127.0.0.1` all'interno del container è il container, non il tuo host. Metti il relay nello stesso container, indirizza esplicitamente l'host, o esegui il relay come sidecar su una rete condivisa. E mantieni la directory del profilo su un volume se stai usando contesti persistenti, altrimenti ogni riavvio del container butta via i cookie di autorizzazione che hai pagato in larghezza di banda per ottenere.

## Cosa coprono le patch, e cosa non copriranno mai

Vale la pena sapere esattamente cosa stai acquistando. La correzione principale di Patchright è la perdita `Runtime.enable` — esegue JavaScript in contesti di esecuzione isolati invece di abilitare il dominio che svela il gioco. Disabilita l'API della Console per chiudere `Console.enable` (quindi il logging `page.on("console")` è sparito, il che è un vero costo quando stai debugando un fallimento del proxy). Riscrive i flag predefiniti di Playwright: aggiunge `--disable-blink-features=AutomationControlled`, rimuove `--enable-automation`, e ripristina `--disable-popup-blocking`, `--disable-component-update`, `--disable-default-apps` e `--disable-extensions`. Raggiunge anche le radici ombra chiuse con locator ordinari.

Leggi quella lista di flag anche come una voce di larghezza di banda. Ripristinare gli aggiornamenti dei componenti e le app predefinite significa un browser che chiama casa in background — attraverso la tua uscita a consumo. Misura il trasferimento di una sessione prima di scalare, e blocca i tipi di risorse immagine, font e media sul contesto per mantenere basso il costo per pagina. Nessuna di queste tocca l'altro muro: un browser patchato su un IP di datacenter bruciato è ancora un IP bruciato, e la richiesta viene rifiutata per reputazione prima che qualsiasi di queste astuzie venga valutata. Controlla un indirizzo con il nostro [controllo qualità IP gratuito](https://quantumproxies.io/ip-checker) prima di concludere che le patch hanno fallito, e metti [proxy residenziali](https://quantumproxies.io/residential-proxies) sotto il browser in modo che i due livelli risolvano problemi diversi.

![Le patch di Patchright superano il controllo di automazione chiudendo la falla di Runtime.enable e riscrivendo i flag di avvio, ma un IP di uscita bruciato viene rifiutato per reputazione prima che tutto questo venga letto. La scheda separa i due compiti: le patch decidono cosa dice il browser, il proxy decide da dove sembra provenire.](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785776555/blog/generated/qp-b10-009-diag2.png)
*Le patch decidono cosa dice il browser di se stesso. I proxy decidono da dove sembra provenire. Correggere uno e ignorare l'altro finisce comunque in un blocco.*

## Domande frequenti

### Come imposto un proxy in Patchright?

Esattamente come in Playwright: passa `proxy={"server": "http://host:port", "username": "USER", "password": "PASS"}` a `chromium.launch()`, `launch_persistent_context()` o `new_context()`. Patchright non modifica il livello proxy, quindi ogni comportamento a monte — la lista di bypass, l'eccezione loopback — si applica invariato.

### Patchright supporta l'autenticazione proxy SOCKS5?

No, ed è una limitazione di Chromium piuttosto che di Patchright: Chromium non ha un meccanismo per le credenziali SOCKS, quindi gli endpoint SOCKS5 autenticati falliscono. Usa la porta HTTP dello stesso gateway con i campi nome utente e password, o autentica tramite whitelist IP e mantieni lo schema SOCKS5 — ogni piano QuantumProxies supporta la whitelist come alternativa a user:pass. L'intero set di soluzioni è nella nostra [guida all'autenticazione SOCKS5 di Playwright](https://quantumproxies.io/blog/playwright-socks5-proxy-authentication), che si applica invariata qui.

### Patchright può usare un proxy diverso per contesto?

Sì, se hai lanciato il browser con un valore di proxy globale — anche un segnaposto — perché Chromium abilita i proxy per contesto solo quando uno è presente all'avvio. L'eccezione è la configurazione del contesto persistente che Patchright raccomanda per discrezione: ciò ti dà un singolo contesto, quindi la rotazione significa un processo separato con la propria directory di profilo.

### Patchright è solo per Chromium?

Sì. Il progetto afferma chiaramente che solo i browser basati su Chromium sono patchati; Firefox e WebKit non sono supportati. Se hai bisogno di discrezione con il motore Firefox con geo derivato dall'uscita del proxy, è uno strumento diverso — vedi la nostra [guida a Camoufox proxy e geoip](https://quantumproxies.io/blog/camoufox-proxy-geoip).

### Vengo ancora bloccato con Patchright?

Su obiettivi difficili, sì. Test indipendenti mostrano che la modalità headless perde ancora un'indicazione di HeadlessChrome, e pagine di sfida che un browser patchato raggiunge ma non può superare. Le patch chiudono i controlli di automazione economici; la reputazione IP, le impronte digitali TLS e la risoluzione delle sfide sono problemi separati che necessitano di risposte separate.

Tratta Patchright per quello che è: una soluzione molto buona per una specifica classe di perdite, fornita senza chiederti di riscrivere una riga di Playwright. Abbinalo a uscite che sono pulite, stabili dove l'identità conta, e verificate prima dell'esecuzione — allora i fallimenti rimanenti riguardano effettivamente il target, non la tua configurazione. Questo è un consiglio tecnico, non legale: automatizza entro la legge e i termini del sito.

[Metti Patchright su uscite residenziali pulite](https://quantumproxies.io/residential-proxies)