Руководство
Прокси в Playwright и Puppeteer: правильная настройка для автоматизации браузера
В Playwright прокси задаётся объектом proxy в вызове launch или newContext, в Puppeteer — через --proxy-server или createBrowserContext и page.authenticate. Отдельный IP для каждого контекста, ограничение SOCKS5 с паролем, sticky-сессии, экономия трафика и таблица ошибок.
Коротко
- В Playwright прокси передаётся в chromium.launch() или browser.newContext() объектом proxy: { server, username, password }; пароль задаётся в отдельном поле, поэтому процентное кодирование не нужно.
- В Puppeteer адрес прокси передают аргументом --proxy-server или через createBrowserContext({ proxyServer }); логин и пароль вводят на каждой странице через page.authenticate() до вызова page.goto().
- Chromium не поддерживает SOCKS5-прокси с логином и паролем: Playwright выдаёт ошибку запуска, Puppeteer возвращает ERR_NO_SUPPORTED_PROXIES. Решение — HTTP-адрес пакета или локальный мост через proxy-chain.
- При неверном пароле прокси Puppeteer не выбрасывает ошибку, а page.goto() возвращает ответ со статусом 407, поэтому значение status() ответа нужно проверять.
- Для sticky-сессии отдельный контекст на каждый идентификатор сессии держит cookies и выходной IP в одной связке; на пакетах с оплатой за ГБ блокировка картинок снижает трафик.
В Playwright прокси задаётся объектом proxy: { server, username, password }, который передают в вызов chromium.launch() или browser.newContext(). В Puppeteer адрес передают Chrome аргументом --proxy-server или через createBrowserContext({ proxyServer }), а логин и пароль вводят через page.authenticate(). Ни в одном из двух инструментов Chromium не поддерживает SOCKS5-прокси с логином и паролем; в этом случае используют HTTP-адрес пакета или локальный мост.
В автоматизации браузера прокси работает иначе, чем в HTTP-клиентах вроде requests или fetch. Через прокси уходят все картинки, скрипты и API-запросы, которые загружает страница, а аутентификацию выполняет сам браузер. В примерах используется адрес шлюза WeProxy gw.weproxy.com.tr:8989. USER и PASSWORD — ваши данные из личного кабинета. Все примеры мы запускали на Playwright 1.65, Puppeteer 25 и Chrome 158 через локальный тестовый прокси.
Как записать адрес прокси в Playwright и Puppeteer?
Оба инструмента ждут адрес прокси-сервера в виде схема://host:port. Даже если целевой сайт работает по HTTPS, адрес HTTP-прокси начинается с http://: браузер отправляет прокси запрос CONNECT и устанавливает TLS-соединение внутри этого туннеля. Адрес без схемы, например gw.weproxy.com.tr:8989, Playwright считает HTTP-прокси.
Не вписывайте логин и пароль в адрес. Playwright принимает их в отдельных полях объекта proxy, а в Puppeteer они передаются через page.authenticate(). Поэтому процентное кодирование не нужно, даже если в пароле есть @ или :: на тестовом прокси пароль p@ss:word без кодирования сработал в обоих инструментах. К тому же пароль, переданный в командной строке, виден в списке процессов системы.
Учётные данные удобнее держать в переменных окружения, чем вписывать в код:
export WEPROXY_USERNAME="USER"
export WEPROXY_PASSWORD="PASSWORD"
Если в личном кабинете вы получили список в формате ip:port:user:pass, разбить строки на части поможет конвертер форматов прокси. Подробно о форматах — в руководстве по форматам прокси.
Как использовать прокси в Playwright?
Проще всего передать прокси при запуске браузера. Тогда все контексты и страницы, открытые из этого браузера, будут выходить через один и тот же прокси:
import { chromium } from 'playwright';
const browser = await chromium.launch({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
},
});
const page = await browser.newPage();
await page.goto('https://api.ipify.org?format=json');
console.log(await page.textContent('body')); // {"ip":"<выходной IP прокси>"}
await browser.close();
В Python те же поля передаются словарём:
import os
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(proxy={
"server": "http://gw.weproxy.com.tr:8989",
"username": os.environ["WEPROXY_USERNAME"],
"password": os.environ["WEPROXY_PASSWORD"],
})
page = browser.new_page()
page.goto("https://api.ipify.org?format=json")
print(page.text_content("body"))
browser.close()
Если какие-то адреса не должны идти через прокси, перечислите домены через запятую в поле bypass, например bypass: 'localhost, .internal.example'. Это удобно для локальных сервисов в тестовой среде. Если в Python нужно отправлять запросы вне браузера, загляните в статью о прокси в Python с примерами для requests и httpx.
Как задать отдельный прокси для каждого контекста в Playwright?
Контекст в Playwright — это отдельный профиль браузера со своими cookies и хранилищем. Если передать прокси в browser.newContext(), один процесс браузера сможет работать с несколькими выходными IP:
import { chromium } from 'playwright';
const browser = await chromium.launch();
const proxied = await browser.newContext({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
},
});
const direct = await browser.newContext();
const p1 = await proxied.newPage();
const p2 = await direct.newPage();
await p1.goto('https://api.ipify.org');
await p2.goto('https://api.ipify.org');
console.log(await p1.textContent('body'), await p2.textContent('body'));
await browser.close();
В тесте все запросы контекста с прокси прошли через прокси, а второй контекст подключился напрямую. В старых версиях Playwright под Windows для прокси на уровне контекста приходилось передавать в launch ещё и прокси-заглушку; в Playwright 1.65 это уже не нужно. Прокси контекста используется и для API-запросов через context.request, так что для обращения к JSON-эндпоинту без открытия страницы отдельный HTTP-клиент не понадобится.
Как использовать прокси с логином и паролем в Puppeteer?
Puppeteer получает прокси через аргумент Chrome --proxy-server. Учётные данные передаются на каждой странице через page.authenticate(), и этот вызов должен идти до page.goto():
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: ['--proxy-server=http://gw.weproxy.com.tr:8989'],
});
try {
const page = await browser.newPage();
await page.authenticate({
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
});
const res = await page.goto('https://api.ipify.org?format=json');
if (res.status() === 407) throw new Error('Учётные данные прокси отклонены');
console.log(await page.evaluate(() => document.body.innerText));
} finally {
await browser.close();
}
В тесте с неверным паролем page.goto() не выбросил ошибку, а вернул ответ с кодом 407. Скрипт без проверки status() может сохранить страницу ошибки прокси как данные. По документации Puppeteer, page.authenticate() в фоне включает перехват запросов (request interception); при большом числе страниц это немного снижает скорость.
В пакетах, где прокси работает по IP whitelist, page.authenticate() не нужен: выходной IP машины, на которой запущен код, должен быть добавлен в личном кабинете. Какой способ действует для какого продукта, сведено в таблицу в руководстве по аутентификации прокси. Краткая инструкция по настройке есть на странице интеграции с Puppeteer.
Как задать разные прокси для контекстов в Puppeteer?
--proxy-server применяется ко всему браузеру. В актуальных версиях Puppeteer вызов browser.createBrowserContext() принимает параметры proxyServer и proxyBypassList, поэтому в одном процессе Chrome каждый контекст может работать через свой прокси:
const browser = await puppeteer.launch();
const ctx = await browser.createBrowserContext({
proxyServer: 'http://gw.weproxy.com.tr:8989',
proxyBypassList: ['localhost'],
});
const page = await ctx.newPage();
await page.authenticate({
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
});
await page.goto('https://api.ipify.org');
Учётные данные задаются на уровне страницы, а не контекста, поэтому повторяйте page.authenticate() на каждой новой странице внутри контекста. Если в старой версии Puppeteer такого параметра нет, для каждого прокси придётся запускать отдельный процесс puppeteer.launch().
Как использовать SOCKS5-прокси при автоматизации браузера?
Chromium не поддерживает аутентификацию по логину и паролю для SOCKS5-прокси. Playwright в этом случае вообще не запускает браузер и выдаёт ошибку Browser does not support socks5 proxy authentication. В Puppeteer, если записать учётные данные в виде --proxy-server=socks5://user:pass@host:port, страница не откроется с ошибкой net::ERR_NO_SUPPORTED_PROXIES. SOCKS5-прокси без аутентификации без проблем работает в обоих инструментах.
Если пакет поддерживает и HTTP, используйте в браузере HTTP-адрес: для трафика страниц у SOCKS5 нет преимуществ. А когда без SOCKS5 не обойтись, поднимите на машине локальный HTTP-мост без аутентификации. Пакет proxy-chain делает это одной строкой:
import puppeteer from 'puppeteer';
import { anonymizeProxy, closeAnonymizedProxy } from 'proxy-chain';
const user = encodeURIComponent(process.env.WEPROXY_USERNAME);
const pass = encodeURIComponent(process.env.WEPROXY_PASSWORD);
const local = await anonymizeProxy(`socks5://${user}:${pass}@gw.weproxy.com.tr:8989`);
// local: http://127.0.0.1:<port>
const browser = await puppeteer.launch({ args: [`--proxy-server=${local}`] });
const page = await browser.newPage();
await page.goto('https://api.ipify.org');
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();
await closeAnonymizedProxy(local, true);
Адрес моста — это URL, поэтому здесь пароль кодируется через encodeURIComponent. Локальный мост слушает только 127.0.0.1; тот же способ подходит и для Playwright, если указать server: local. Чем HTTP отличается от SOCKS5, рассказано в статье HTTP vs SOCKS5. Мобильный 5G прокси на реальных SIM-картах работает только по HTTP, так что с ним мост не нужен.
Настройки прокси в Playwright и Puppeteer: сравнение
| Параметр | Playwright | Puppeteer |
|---|---|---|
| Прокси для всего браузера | launch({ proxy: { server } }) | args: ['--proxy-server=...'] |
| Прокси на контекст | newContext({ proxy }) | createBrowserContext({ proxyServer }) |
| Логин и пароль | proxy.username, proxy.password | page.authenticate() на каждой странице |
| Адреса в обход прокси | bypass: 'a.com, .b.com' | proxyBypassList или --proxy-bypass-list |
| SOCKS5 с паролем | Не поддерживается, ошибка запуска | Не поддерживается, ERR_NO_SUPPORTED_PROXIES |
| Поведение при неверном пароле | page.goto() выбрасывает ошибку | page.goto() возвращает ответ 407 |
| Поддерживаемые языки | JavaScript, Python, Java, .NET | JavaScript |
В Playwright учётные данные входят в настройку прокси, поэтому в задачах с множеством контекстов код получается короче. Если проект уже написан на Puppeteer, менять инструмент незачем: createBrowserContext даёт ту же гибкость.
Какой тип прокси подходит для автоматизации браузера?
Браузер создаёт гораздо больше трафика, чем HTTP-клиент. Одна страница товара с картинками, шрифтами и скриптами может весить несколько мегабайт. Поэтому продукт выбирают и по цели, и по модели оплаты:
| Задача | Подходящий продукт | Почему |
|---|---|---|
| Многостраничный скрапинг, SERP и мониторинг цен | Rotating Residential IPv4 | Sticky- и rotating-сессии, таргетинг по стране и городу, HTTP и SOCKS5 |
| Большие объёмы, незащищённые сайты | Rotating Datacenter IPv4 | Оплата за ГБ, sticky-сессия на 1–5 минут |
| Долгая сессия с логином, постоянный IP на аккаунт | ISP Proxy или Static Residential IPv4 | IP не меняется весь период; у Static Residential нет лимита трафика |
| Мобильная версия и тестирование приложений | Мобильный 5G прокси | Реальные SIM, только HTTP и логин/пароль |
На продуктах с оплатой за ГБ блокировка картинок и медиа заметно сокращает трафик. В Playwright для этого хватит одного route на уровне контекста:
await context.route('**/*', (route) => {
const type = route.request().resourceType();
return ['image', 'media', 'font'].includes(type) ? route.abort() : route.continue();
});
Чтобы прочитать цену или наличие товара, внешний вид страницы не нужен; обычно хватает текста и данных JSON-LD. Как устроить мониторинг цен в период распродаж, подробно описано в руководстве по отслеживанию цен в Чёрную пятницу. О выборе типа IP и сессии для скрапинга рассказывает и страница веб-скрапинг.
Как связать sticky-сессию с контекстом браузера?
У rotating-шлюза адрес прокси не меняется, а выходной IP берётся из пула и меняется. При логине, работе с корзиной или многошаговой формой все шаги должны идти с одного IP. Для этого в residential-пулах WeProxy к имени пользователя добавляют идентификатор сессии. Формат имени пользователя и длительность сессии для своего продукта возьмите в личном кабинете.
В автоматизации браузера чище всего открывать отдельный контекст на каждую сессию. Тогда cookies, хранилище и выходной IP остаются в одной связке:
import { chromium } from 'playwright';
// Имена пользователей копируются из личного кабинета; у каждого профиля свой session ID.
const PROFILES = ['USER_WITH_SESSION_1', 'USER_WITH_SESSION_2'];
const browser = await chromium.launch();
for (const username of PROFILES) {
const context = await browser.newContext({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username,
password: process.env.WEPROXY_PASSWORD,
},
locale: 'tr-TR',
timezoneId: 'Europe/Istanbul',
});
const page = await context.newPage();
await page.goto('https://api.ipify.org');
console.log(username, await page.textContent('body'));
await context.close();
}
await browser.close();
locale и timezoneId заставляют сайт показывать язык и формат дат под страну прокси. В примере это турецкий IP, и с такими настройками страница не покажет английский формат даты или чужую валюту. Два контекста не должны использовать один и тот же идентификатор сессии. Какие задачи требуют sticky, а какие rotating, разобрано с таблицей сценариев в руководстве sticky или rotating. Те же настройки согласования для антидетект-браузеров описаны в статье антидетект-браузер + прокси.
Как проверить, что прокси работает, и что означают ошибки?
Самый быстрый тест — открыть в одном браузере два контекста, с прокси и без, и сравнить ответы api.ipify.org. Если значения совпадают, настройка прокси до браузера не доходит. Страну и сеть выходного IP покажет инструмент My IP. Чтобы проверить прокси отдельно от кода, используйте proxy checker: если там прокси работает, а в браузере нет, ищите проблему в настройках скрипта.
Ошибки, полученные на тестовом прокси с Chrome 158:
| Ситуация | Playwright | Puppeteer |
|---|---|---|
| Учётные данные не переданы | net::ERR_INVALID_AUTH_CREDENTIALS | net::ERR_INVALID_AUTH_CREDENTIALS |
| Неверный пароль | net::ERR_HTTP_RESPONSE_CODE_FAILURE | Ошибки нет, статус ответа 407 |
| Не удалось подключиться к прокси | net::ERR_PROXY_CONNECTION_FAILED | net::ERR_PROXY_CONNECTION_FAILED |
HTTP-прокси записан с https:// | net::ERR_PROXY_CONNECTION_FAILED | net::ERR_PROXY_CONNECTION_FAILED |
| SOCKS5 с паролем | Browser does not support socks5 proxy authentication | net::ERR_NO_SUPPORTED_PROXIES |
При ошибках аутентификации повторные попытки ничего не дадут; сначала убедитесь, что пакет активен и имя пользователя совпадает с указанным в личном кабинете. Если ERR_PROXY_CONNECTION_FAILED появляется постоянно, возможно, ваша сеть или облачный провайдер закрывает исходящие соединения на порт 8989. Из какого слоя приходят коды 403 и 429 от целевого сайта после установки соединения с прокси, объясняет руководство по кодам ошибок прокси. Обычно при таких кодах хватает повторов с растущим интервалом и меньшего числа параллельных запросов.
Автоматизация браузера: соблюдение правил и безопасность
Если ваша автоматизация собирает данные, соблюдайте файл robots.txt целевого сайта (RFC 9309) и его условия использования, даже если запросы идут через прокси, и держите число одновременных контекстов на уровне, который сайт выдержит. Требования KVKK (Турция) и GDPR к обработке персональных данных действуют независимо от прокси. Что разрешено и что запрещено при работе с сервисами WeProxy, написано на странице допустимого использования.
Скриншоты и trace-файлы содержат содержимое страниц, а иногда и сессионные cookies; проверяйте их, прежде чем кому-то отправлять. Не выводите пароль прокси в логи и сообщения об ошибках. Для запросов вне браузера подойдут примеры с undici и axios из статьи о прокси в Node.js: они работают с теми же данными прокси, что и Playwright. Все параметры API описаны в документации Playwright по прокси и в документации Puppeteer BrowserContextOptions.
Частые вопросы
Как задать прокси с логином и паролем в Playwright?
Передайте объект proxy в вызов chromium.launch() или browser.newContext(): в поле server укажите адрес http://host:port, а в поля username и password — данные из личного кабинета. Учётные данные не вписываются в адрес, поэтому кодирование не нужно, даже если в пароле есть @ или :. В Python те же поля передаются словарём p.chromium.launch(proxy={...}). Все контексты и страницы этого браузера выходят через один прокси.
Как настроить аутентификацию прокси в Puppeteer?
Запустите браузер с аргументом --proxy-server=http://host:port и на каждой новой странице вызывайте page.authenticate({ username, password }) до page.goto(). Не добавляйте учётные данные в адрес --proxy-server: Chromium не поддерживает такой формат, а пароль будет виден в списке процессов. При неверном пароле Puppeteer не выбрасывает ошибку, а возвращает ответ со статусом 407, поэтому проверяйте status() результата page.goto().
Могут ли разные страницы в одном браузере работать через разные прокси?
Да, на уровне контекста. В Playwright каждому вызову browser.newContext() передаётся свой объект proxy. В актуальных версиях Puppeteer то же делает browser.createBrowserContext({ proxyServer }), а учётные данные по-прежнему вводятся через page.authenticate(). Страницы внутри одного контекста используют общий прокси; если нужен отдельный прокси для каждой страницы, открывайте для каждой свой контекст.
Почему Playwright выдаёт ошибку «Browser does not support socks5 proxy authentication»?
Chromium не поддерживает аутентификацию по логину и паролю для SOCKS5-прокси, и Playwright отлавливает это ещё до запуска браузера. Если ваш пакет поддерживает и HTTP, используйте в браузере HTTP-адрес. Если нужен именно SOCKS5, поднимите функцией anonymizeProxy из пакета proxy-chain HTTP-мост без аутентификации на 127.0.0.1 и передайте браузеру этот адрес.
Как сократить трафик прокси при автоматизации браузера?
Основную часть трафика составляют картинки, шрифты и видео. В Playwright прерывайте через context.route() запросы типов image, media и font; в Puppeteer то же делается через page.setRequestInterception(true). Для задач, где нужно прочитать цену, наличие или текст, внешний вид страницы не важен. На rotating-пакетах с оплатой за ГБ такая настройка заметно снижает расход.









