TL;DR
- Playwright соединяется с существующим браузером Chromium с помощью
chromium.connectOverCDP();launch()запускает другой браузер. - Управляемая сессия должна быть
ready, прежде чем вы запросите временные учетные данные CDP и подключите клиента. - Ключ API жизненного цикла и токен доступа CDP аутентифицируют разные соединения и не могут заменять друг друга.
- Успешное рукопожатие WebSocket подтверждает подключение; проверка страницы подтверждает, что ваша задача достигла ожидаемого результата.
- Повторное использование существующей авторизованной вкладки требует явного выбора страницы внутри той же запущенной сессии.
- Отключение Playwright не подтверждает, что управляемый браузер остановился; остановите сессию отдельно и проверьте
ended.
Как работает подключение Playwright через CDP?
Playwright подключение через CDP присоединяет вашу программу на Node.js к уже запущенному браузеру Chromium через Протокол инструментов разработчика Chrome. Скрипт запускается на вашем ноутбуке или рабочем сервере; браузер отображает страницы и делает запросы к веб-сайтам на удаленном хосте. Хостинг конечной точки, таким образом, устраняет необходимость устанавливать бинарный файл браузера на этом рабочем сервере, оставляя селекторы, проверки и решения задач в вашем коде.
Nstdata Cloud Browser предоставляет управляемые облачные браузеры для автоматизации браузеров и ИИ-агентов. Этот учебник использует сессию, созданную на панели управления, чтобы вы могли наблюдать за браузером во время подтверждения подключения. Финальная задача открывает публичную примерную страницу, проверяет ее HTTP-ответ и подтверждает заголовок. Ничего не отправляется на аккаунт или форму.
Различие имеет значение при расширении существующего рабочего процесса веб-скрапинга Playwright: замените соединение с браузером целенаправленно, затем проверьте выбор контекста и очистку. Копирование удаленной конечной точки в локальную конфигурацию запуска не создает ту же модель исполнения.
Какой способ подключения Playwright выбрать?
Используйте connectOverCDP() для конечной точки Chromium CDP, connect() для совместимого сервера Playwright и launch(), когда ваше приложение управляет локальным процессом браузера. Эти методы общаются с разными контрактами сервера. API Playwright BrowserType определяет CDP только для Chromium и с меньшей точностью, чем родной протокол Playwright.
| Метод | Удаленный интерфейс | Подходящая отправная точка |
|---|---|---|
chromium.launch() | Исполняемый файл браузера, запущенный вашим кодом | Локальная разработка и браузер, которым вы управляете сами |
chromium.connect() | Конечная точка сервера браузера Playwright | Управляемое развертывание клиента/сервера Playwright |
chromium.connectOverCDP() | Конечная точка CDP Chromium | Существующий браузер или совместимая управляемая сессия |
Совместимость CDP не обещает идентичного поведения для каждой расширенной функции Playwright. Тестируйте операции, которые ваше приложение действительно требует, с управляемым браузером. Основная навигация не устанавливает, что отслеживание, рабочие процессы расширений, загрузки или каждая опция контекста ведут себя так же, как локально запущенный браузер.
Что нужно подготовить перед подключением?
Вам нужен Node.js 22.12 или более поздняя версия, playwright-core, доступная рабочая область Nstdata, готовая сессия и правильный бизнес-ключ API. Получите личный ключ в разделе Settings → Account или ключ члена команды в разделе Members. Подтвердите баланс рабочей области и текущие разрешения на параллельные запросы перед запуском браузера.
| Поле | Откуда оно берется | Куда оно принадлежит |
|---|---|---|
NSTDATA_API_KEY | Ваш аккаунт или ключ команды | HTTP-заголовок жизненного цикла x-api-key, без Bearer |
NSTDATA_TEAM_ID | Присоединенная команда, при использовании личного ключа | Необязательный x-team-id в каждом запросе жизненного цикла |
NSTDATA_SESSION_ID | Сессия, которую вы запустили | Пути для поиска сессий и конечной точки учетных данных |
cdpUrl | Ответ с учетными данными автоматизации | Аргумент конечной точки connectOverCDP() |
headerName, accessToken | Тот же ответ с учетными данными | Заголовки соединения CDP |
expiresAt | Тот же ответ с учетными данными | Проверка истечения перед присоединением |
Ключ члена команды привязан к своей команде; добавление другого ID команды не переключает его. Поддерживайте контекст рабочей области последовательным на протяжении всего рабочего процесса. Не используйте JWT входа в панель управления в качестве бизнес-ключа API.
Клиент ниже был протестирован через реальное соединение CDP с новым, изолированным локальным Chromium. Ветвь учетных данных Nstdata требует ваш API-ключ и не была выполнена по платному аккаунту. Локальное выполнение проверяет операции клиента; это не устанавливает аутентификацию управляемого аккаунта или поведение выставления счетов.
Как подключить Playwright к Nstdata Cloud Browser?
Подключитесь, создав видимую сессию, получив учетные данные для этой же сессии и передав эти учетные данные Playwright. Текущий документ по автоматизации браузера описывает жизненный цикл и разделение учетных данных, используемые ниже.
Шаг 1: Запустите сессию браузера
Откройте Cloud Browser → Playground, выберите необходимое рабочее пространство и настройте Session Name, Proxy Country, Resource Class и Session Duration. Нажмите Launch Browser. Подождите, пока область инструментов не покажет Running, и превью станет доступным.
[Скриншот: Игровая площадка, показывающая запущенную сессию и область инструментов CDP, со скрытыми всеми URL-адресами доступа и токенами.]
Выберите настройки прокси и среды перед запуском. Страна прокси выбирает место выхода; это не гарантирует фиксированный IP. Продолжительность сессии - это автоматический лимит времени жизни, который отличается от времени ожидания навигации в вашем сценарии.
Шаг 2: Установите зависимость клиента
Создайте каталог проекта и установите версию, используемую в этом примере. playwright-core предоставляет клиент без загрузки браузера для рабочего процесса.
mkdir remote-playwright-demo cd remote-playwright-demo npm init -y npm install --save-exact playwright-core@1.65.1
Шаг 3: Сохраните помощник для подключения
Сохраните следующий модуль как cloud-api.mjs. Он находит оригинальную сессию, требует state === 'ready', запрашивает учетные данные и проверяет возвращённую идентичность сессии и срок действия. Ветвь только для обратной связи предназначена для изолированного тестирования браузера разработчика; в производственной среде следует использовать ветвь учетных данных Nstdata.
Предварительное условие для учетных данных: Запросы API Nstdata в этом модуле требуют вашего ключа, идентификатора сессии и опционального контекста команды. Указывайте их локально; никогда не вставляйте их реальные значения в систему контроля версий или общий журнал.
const root = 'https://api.nstdata.io/api/v1/cloud-browser'; export async function api(method, path, body) { const key = process.env.NSTDATA_API_KEY; if (!key) throw new Error('Set NSTDATA_API_KEY'); const headers = { 'x-api-key': key }; if (process.env.NSTDATA_TEAM_ID) headers['x-team-id'] = process.env.NSTDATA_TEAM_ID; if (body) headers['content-type'] = 'application/json'; let response; try { response = await fetch(root + path, { method, headers, redirect: 'error', body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(20_000), }); } catch { throw Object.assign(new Error('API transport failed; reconcile the original operation'), { retryable: true }); } const retryable = response.status === 429 || response.status >= 500; let result; try { result = await response.json(); } catch { throw Object.assign(new Error('Invalid API JSON'), { retryable }); } if (!response.ok || result.err === true || result.success === false) { throw Object.assign(new Error(`Cloud Browser API HTTP ${response.status}`), { retryable }); } if (!result.data) throw new Error('Missing API data'); return result.data; } export async function connection(id) { if (!id) throw new Error('Set NSTDATA_SESSION_ID'); const path = `/sessions/${encodeURIComponent(id)}`; const session = await api('GET', path); if (session.state !== 'ready') throw new Error(`Session is ${session.state}, not ready`); const c = await api('POST', path + '/automation-credentials'); if (c.sessionId !== id || !c.headerName || !c.accessToken || !(Date.parse(c.expiresAt) > Date.now()) || new URL(c.cdpUrl).protocol !== 'wss:') { throw new Error('Invalid or expired CDP credentials'); } return { endpoint: c.cdpUrl, headers: { [c.headerName]: c.headerName.toLowerCase() === 'authorization' ? `Bearer ${c.accessToken}` : c.accessToken }, }; } export async function endpoint() { // An isolated local CDP endpoint can test the client without managed credentials. if (process.env.LOCAL_CDP_URL) { const url = new URL(process.env.LOCAL_CDP_URL); if (!['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)) { throw new Error('LOCAL_CDP_URL must use loopback'); } return { endpoint: url.href, headers: {} }; } return connection(process.env.NSTDATA_SESSION_ID); }
Шаг 4: Сохраните задачу проверки страницы
Сохраните этот скрипт как connect-playwright.mjs. Скрипт создает страницу внутри контекста по умолчанию и закрывает только эту страницу перед освобождением клиента. Ознакомьтесь с семантикой очистки подключенного браузера перед тем, как адаптировать очистку для общей сессии.
Предварительное условие для учетных данных: управляемый путь выполнения требует настройки среды из Шага 3. Логика страницы и реальная рукопашная CDP были проверены локально.
import { chromium } from 'playwright-core'; import { endpoint } from './cloud-api.mjs'; async function main() { const config = await endpoint(); let browser; let page; try { browser = await chromium.connectOverCDP(config.endpoint, { headers: config.headers, timeout: 30_000, }); const context = browser.contexts()[0]; if (!context) throw new Error('Default context is unavailable'); page = await context.newPage(); const response = await page.goto(process.env.TARGET_URL || 'https://example.com/', { waitUntil: 'domcontentloaded', timeout: 30_000, }); if (!response?.ok()) throw new Error('Navigation did not return a successful response'); const heading = await page.getByRole('heading', { name: 'Example Domain', exact: true }).innerText(); console.log(JSON.stringify({ connected: browser.isConnected(), heading, taskPassed: true })); } finally { try { if (page) await page.close(); } finally { if (browser) await browser.close(); } } } main().catch(() => { console.error("Browser task failed; inspect private diagnostics and the original session."); process.exitCode = 1; });
Шаг 5: Запустите тест подключения
Создайте приватный файл .env, содержащий NSTDATA_API_KEY и NSTDATA_SESSION_ID, с вашими реальными значениями после =. Добавьте NSTDATA_TEAM_ID, только если это применимо. Исключите этот файл из системы контроля версий, затем выполните команду ниже. Оставьте LOCAL_CDP_URL неустановленным для управляемой сессии.
node --env-file=.env connect-playwright.mjs
Для целевого по умолчанию успехом является JSON-объект, содержащий connected: true, heading: "Example Domain" и taskPassed: true. лоткатор на основе ролей проверяет результат страницы, а не рассматривает подключенный сокет как завершение задачи. Если вы измените TARGET_URL, измените утверждение, чтобы оно соответствовало предполагаемой авторизованной странице.
Шаг 6: Остановите управляемую сессию
Вернитесь к оригинальной сессии и нажмите Stop Browser. Подождите, пока сессия не завершится. В API-собственном задании вызовите DELETE /api/v1/cloud-browser/sessions/{sessionId} и опрашивайте ту же сессию, пока ее state не станет ended. Закрытие превью-вкладки или освобождение Playwright не является этой операцией остановки.
Как использовать Cloud Browser в рабочем процессе Playwright?
Nstdata Cloud Browser вписывается в процесс Playwright, когда ваша команда хочет управляемого выполнения браузера с видимыми элементами управления сессией. Ваше приложение сохраняет право собственности на задачу, схему вывода и критерии приемки. Сервис предоставляет удалённую сессию браузера и ее соединительную поверхность. Один и тот же исполняющий браузер может быть просмотрен вручную и управляться через CDP. Это делает неудачную задачу проверяемой, не предполагая, что скрипт выбрал правильную страницу или учетную запись.
- Управляемое выполнение: подключите клиента от работника, который не имеет своей собственной установки Chromium; сохраняйте таймауты и утверждения на уровне приложения.
- Конфигурация прокси на уровне сессии: используйте выбранную встроенную конфигурацию прокси, не добавляя отдельный прокси-шлюз к этому клиентскому скрипту; измеряйте трафик прокси наряду с временем выполнения браузера.
- Живая инспекция: наблюдайте за активной страницей и доступной диагностикой, когда селектор не срабатывает; инспекция автоматически не исправляет логику приложения.
Используйте модель ценообразования Cloud Browser для разделения времени выполнения, трафика прокси и любой необязательной использования CAPTCHA. Начните с краткосрочной авторизованной задачи и сравните стоимость за принятый результат. Введение в Cloud Browser объясняет более широкую роль продукта, в то время как руководство по автоматизации браузера Node.js охватывает шаблоны на уровне страниц.
Почему подключение CDP не работает или открывает другую страницу?
Соединение CDP не удается, когда его конечная точка, учетные данные, состояние сессии или сетевой путь недействительны; неправильная страница обычно указывает на неверный выбор контекста или вкладки.
| Симптом | Вероятная причина | Следующее действие |
|---|---|---|
| Не удается аутентификация HTTP в жизненном цикле | Неправильный ключ или команда контекста | Проверьте x-api-key и последовательный x-team-id |
| Не удается аутентификация CDP | Просроченный токен или неверный заголовок | Запросите ту же готовую сессию и запросите свежие учетные данные |
| Браузер подключается, но приложение вышло из системы | Использовалась новая страница/контекст или другая сессия | Явно выберите существующую авторизованную вкладку |
| Таймаут утверждения заголовка | Неправильная страница, перенаправление или измененное содержимое | Проверьте выбранную страницу и ожидаемый маркер |
| Сессия завершена | Время жизни истекло или браузер был остановлен | Начните новую задачу; не используйте старые учетные данные |
Избегайте многократного перезапуска всей работы для устранения проблем с аутентификацией. Новый идентификатор сеанса может скрыть оригинальный сбой и создать дополнительное использование времени выполнения. Храните идентификаторы запросов/сессий в операционных журналах, скрывая при этом токены доступа и полные URL-адреса CDP.
Что проверить перед запуском интеграции в продакшен?
Проверьте управляемое подключение, фактическую задачу страницы и подтвержденное завершение сеанса как отдельные проверки. Проведите узкий производственный канареечный тест с ожидаемым рабочим пространством и целевым объектом, зафиксируйте его идентификатор сеанса и принятый вывод, и подтвердите завершение позже. Расширяйте только после того, как ваши необходимые взаимодействия будут работать с удаленным браузером. Это дает команде повторяемый тест на прием вместо демонстрации только подключения.
FAQ
Q: Может ли Playwright подключаться к Firefox или WebKit через CDP?
Нет. Подключение CDP Playwright предназначено для браузеров на основе Chromium. Используйте подходящий поддерживаемый рабочий процесс браузера, когда ваш тест требует Firefox или WebKit.
Q: Мне нужно устанавливать Chromium на рабочем месте?
Для этого примера удаленного подключения не требуется бинарный файл браузера. Установите playwright-core на рабочем месте и подключитесь к браузеру, работающему в управляемой сессии.
Q: Переиспользует ли сценарий быстрого старта мою открытую вкладку?
Нет. Этот сценарий создает новую страницу. Для ручной передачи входа выберите существующую страницу по ожидаемому источнику, пути и маркеру учетной записи внутри одной и той же работающей сессии.
Q: Могу ли я использовать бизнес-ключ API в качестве токена CDP?
Нет. Используйте бизнес-ключ для запросов жизненного цикла, затем получите краткосрочный accessToken и headerName из ответа automation-credentials.
Q: Сброс подключения восстанавливает ли продолжительность сеанса?
Нет. Повторное подключение клиента не продлевает срок действия управляемого сеанса. Запросите оригинальное состояние перед запросом новых учетных данных.
Q: Достаточно ли успешной проверки заголовка для производства?
Проверка заголовка достаточна для этой демонстрации подключения. Производственные задачи должны иметь свои собственные критерии приемки, обработку ошибок и подтвержденную очистку, используя только веб-сайты и учетные записи, которые вы уполномочены автоматизировать.





