Подключение к удаленному браузеру Puppeteer использует puppeteer.connect() и конечную точку WebSocket удаленного браузера.
puppeteer-core подходит, когда ваш рабочий процесс подключается к браузеру, который уже запущен другой службой.
HTTP-вызовы жизненного цикла Nstdata используют ключ бизнес-API; соединения CDP используют отдельно выданные, краткосрочные учетные данные.
Используйте browserWSEndpoint для возвращаемого URL-адреса CDP WebSocket и передавайте аутентификацию через возвращаемое имя заголовка.
Установите defaultViewport: null, когда хотите сохранить существующий видимый экран удаленного браузера, а не применить стандартное переопределение Puppeteer.
browser.disconnect() оставляет удаленный браузер запущенным; остановите сеанс Nstdata отдельно после выполнения задачи.
Что такое подключение удаленного браузера Puppeteer?
Подключение удаленного браузера Puppeteer позволяет клиенту Node.js управлять уже запущенным браузером вместо запуска локального исполняемого файла. Puppeteer отправляет команды автоматизации через протокольное соединение; браузер выполняет навигацию, выполнение JavaScript и рендеринг на своем собственном хосте. Это полезно, когда работники должны оставаться небольшими или оператору необходимо видеть ту же сессию, которую контролирует скрипт.
Nstdata Cloud Browser предоставляет управляемые облачные браузеры для автоматизации браузера и ИИ-агентов с поверхностью соединения CDP. В этом руководстве панель инструментов отвечает за создание и остановку сеансов, в то время как небольшой клиент Puppeteer владеет одной временной страницей. Разделение этих обязанностей упрощает проверку первой интеграции.
Пример валидирует общедоступную страницу без входа в учетную запись или отправки данных. Для более широкого введения в структуру существующее охватывает автоматизацию локальных страниц. Эта статья сосредоточена на дополнительном контракте, введенном удаленным браузером: идентичность конечной точки, срок действия учетных данных, право собственности на страницу и остановка.
Следует ли использовать Puppeteer или Puppeteer-Core?
Используйте puppeteer-core, когда ваше приложение предоставляет существующую конечную точку браузера и не нуждается в управляемой загрузке браузера Puppeteer. Руководство по установке Puppeteer различает полный пакет и основную библиотеку. Выбор основного пакета не создает браузер; совместимый удаленный браузер уже должен быть доступен.
Решение
Использование в этом учебнике
Создание браузера
Nstdata Playground
Пакет клиента
puppeteer-core
Метод подключения
puppeteer.connect()
Опция конечной точки
browserWSEndpoint
Право собственности на страницу
Создайте и закройте одну демонстрационную страницу
Управляемая очистка
Остановите оригинальный сеанс в панели инструментов
Не путайте выполнение Puppeteer на вашем рабочем процессе Node.js с упаковкой его API внутри клиентской веб-страницы. Этот пример представляет собой скрипт на стороне сервера. Ключи бизнес-API остаются в среде рабочего процесса и никогда не попадают в пакет JavaScript веб-сайта.
Какие учетные данные и настройки вам нужны?
Вам нужен готовый сеанс Cloud Browser, Node.js 22.12 или новее и ключ бизнес-API для рабочего пространства, которое владеет сеансом. Получите личный ключ из Settings → Account, или используйте ключ члена команды из Members. Проверьте текущий баланс рабочего пространства и разрешение на одновременные запросы перед запуском.
Идентификатор сеанса идентифицирует запущенный браузер. NSTDATA_API_KEY становится заголовком жизненного цикла x-api-key без префикса Bearer. Личный ключ может опционально выбирать присоединенную команду через NSTDATA_TEAM_ID, отправленный как x-team-id; ключ члена команды использует свою привязанную команду. Сохраняйте этот контекст одинаковым для поиска и выдачи учетных данных.
Конечная точка учетных данных возвращает cdpUrl, headerName, accessToken и expiresAt для одной и той же сессии. Эти значения аутентифицируют соединение WebSocket. Они не являются многоразовым заменителем ключа бизнес-API, и старый токен не восстанавливает завершенный браузер.
Ручное сочетание Puppeteer, навигация, утверждение и отключение этого учебника были выполнены против изолированного локального Chromium. Ветвь управлении учетными записями требует вашего ключа и не была протестирована на платном рабочем пространстве Nstdata. Рассматривайте ваше первое управляемое выполнение как интеграционную канарейку, включая остановку сеанса в приемке.
Как подключить Puppeteer к облачному браузеру?
Подключите Puppeteer, запустив сеанс, установив основной клиент, получив специфические для сеанса учетные данные и передав их в puppeteer.connect(). API подключения Puppeteer является клиентской ссылкой для этой операции.
Шаг 1: Создайте видимый удаленный сеанс
Откройте Cloud Browser → Playground и выберите нужное персональное или командное рабочее пространство. Установите Session Name, Proxy Country, Resource Class и Session Duration, затем нажмите Launch Browser. Подождите, пока появится Running и доступный предварительный просмотр.
[Скриншот: Сессия Cloud Browser в работе с видимым рабочим пространством и именем сессии; скрыть ссылки доступа, токены и содержимое частной страницы.]
Настройте страну прокси перед началом сессии. Клиент наследует сконфигурированный сетевой путь сессии, поэтому в этом примере не передается второй URL прокси в Puppeteer. Страна прокси, язык и часовой пояс - это отдельные настройки; выбор страны не гарантирует фиксированный адрес или аутентифицированную сессию веб-сайта.
Шаг 2: Установите Puppeteer-core
Инициализируйте проект и установите точную версию клиента, используемую в примере. Сохраните сгенерированный файл блокировки, чтобы другой работник мог воспроизвести выбор зависимости.
mkdir cloud-puppeteer-demo
cd cloud-puppeteer-demo
npm init -ynpminstall --save-exact puppeteer-core@25.17.0
Шаг 3: Сохраните помощник по учётным данным
Сохраните следующий код как cloud-api.mjs. Он запрашивает сессию перед запросом учётных данных для автоматизации и создает заголовок CDP из возвращаемого поля. Когда это поле - Authorization, значение получает префикс Bearer; другие возвращенные имена заголовков получают необработанный токен доступа.
Предварительное требование к учётным данным: ветка Nstdata требует вашего бизнес-API-ключа и готовой сессии. Опция локальной петли помощника существует только для отдельного локального тестового браузера и должна оставаться неустановленной для управляемого рабочего процесса.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('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 =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('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{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
Шаг 4: Сохраните задание браузера
Сохраните этот скрипт как connect-puppeteer.mjs. Он открывает одну страницу, проверяет ответ навигации и подтверждает ожидаемый заголовок перед закрытием страницы и отключением. Значения таймаута ограничивают эту демонстрацию; они не являются квотами сервиса.
Предварительное требование к учётным данным: управляемое выполнение требует ключа и настройки окружения сессии, описанные выше. Ветвь клиента была выполнена через реальное локальное подключение CDP.
defaultViewport: null сохраняет существующий размер окна вместо наложения значения по умолчанию Puppeteer. Это не изменяет отпечаток экрана сессии, страну прокси или уровень зума Live View. Если вашей задаче требуется определенный размер окна, установите его намеренно и проверьте отображаемую компоновку после подключения.
Шаг 5: Выполните проверку страницы
Создайте частный файл .env с NSTDATA_API_KEY и NSTDATA_SESSION_ID, плюс NSTDATA_TEAM_ID, только когда это необходимо. Исключите его из управления версиями. Выполните следующую команду из каталога, содержащего оба модуля.
node --env-file=.env connect-puppeteer.mjs
Для значения по умолчанию скрипт выводит объект JSON с heading: "Example Domain" и taskPassed: true. Одно только соединение с конечной точкой не даст такое утверждение. Если вы изменили целевое значение, обновите селектор и ожидаемое значение вместе; несвязная страница с h1 не является достаточным доказательством.
Шаг 6: Остановите созданную сессию
Щелкните Stop Browser в оригинальной сессии и дождитесь завершения. Метод отключения Puppeteer освобождает клиентское соединение, оставляя браузер работающим. Управляемое завершение работы браузера остается отдельным действием.
Для задачи, принадлежащей API, остановите с помощью DELETE /api/v1/cloud-browser/sessions/{sessionId} и опрашивайте, пока state не станет ended. Сбой рабочего процесса может пропустить обычную очистку, поэтому сохраните идентификатор сессии вне временной памяти процесса. Используйте текущий жизненный цикл автоматизации браузера при реализации этого служб владельца.
Как Nstdata может поддерживать рабочий процесс Puppeteer за пределами демонстрации?
Nstdata Cloud Browser предоставляет хостинговый браузер, в то время как Puppeteer сохраняет контроль над навигацией и взаимодействием со страницей. Разработчик может прикрепить скрипт из существующего запускающего задания без развертывания Chromium на каждом рабочем узле. Оператор может проверить тот же работающий браузер, когда задаче требуется внимание. Конфигурация сессии обеспечивает контролируемую точку запуска для ресурсов и местоположения прокси. Приложение по-прежнему решает, какая страница является действительной, какой вывод приемлем, и когда сессия должна остановиться.
Управляемый исполняемый браузер: переместите выполнение браузера за пределы развертывания рабочего процесса, затем протестируйте свои конкретные операции Puppeteer против этого времени выполнения.
Встроенная конфигурация прокси: выберите поддерживаемую страну прокси сессии, не поддерживая отдельный прокси-шлюз в клиенте примера; контролируйте расходы на получаемый трафик.
Live View и диагностика: наблюдайте за рендерингом и проверяйте доступную информацию из Консоли или Сети, когда ожидание страницы не удается.
Явный жизненный цикл: используйте состояния сессии, чтобы различать проблемы с подключением и истекший или остановленный браузер.
Посмотрите цены на использование Cloud Browser перед расширением. Время выполнения, трафик прокси и необязательное использование CAPTCHA являются отдельными компонентами стоимости; удаленное соединение не является фиксированной заменой для неограниченной работы браузера. Введение в продукт Cloud Browser описывает границы продукта, а практическое руководство Playwright предоставляет дополнительный подход к проектированию задач браузера.
Как повторно использовать существующую вкладку без потери состояния?
Повторно используйте существующую вкладку, идентифицируя ее внутри одной и той же сессии, а не создавая новый браузер или выбирая первый элемент в browser.pages(). Перечислите доступные страницы, сопоставьте ожидаемый источник и путь, и требует точно одного кандидата. Затем подтвердите конкретный аккаунт приложения или маркер рабочего пространства перед чтением данных или нажатием кнопок управления.
Демонстрация намеренно использует newPage(), потому что не имеет состояния входа, которое нужно сохранять. Передача человеку имеет другой контракт: не переходить на выбранной вкладке обратно по URL для входа, создать инкогнито-контекст или предполагать, что новая сессия содержит куки предыдущей сессии. Приложение также может аннулировать свой вход независимо от времени жизни браузера.
Почему браузер подключается, но задача завершается неудачно?
Браузер может подключаться успешно, в то время как выбранная страница перенаправляется, неполна, выведена из системы или отличается от ожидаемого приложения. Диагностируйте уровень задачи после проверки уровня соединения.
Симптом
Причина для исследования
Исправление
Запрос учетных данных завершается неудачно
Несоответствие API-ключа или команды
Сохраняйте последовательность бизнес-аутентификации и рабочего пространства
WebSocket отвергает аутентификацию
Истекший или неправильно применённый CDP токен
Запросите свежие учетные данные для той же готовой сессии
Заголовок отсутствует
Навигация или рендеринг не достигли ожидаемого состояния
Проверьте ответ, URL страницы приватно и конкретный маркер готовности
Отсутствует существующий вход
Новая вкладка/контекст или неправильная сессия браузера
Выберите оригинальную сессию и целевую страницу
Браузер остаётся в истории как работающий
Клиент отключился без остановки
Остановите через владельца жизненного цикла и подтвердите ended
Не добавляйте произвольные задержки перед проверкой этих условий. Ждите конкретного элемента или ответа, который доказывает готовность. Долгий таймаут просто задерживает ошибку, когда скрипт наблюдает за неправильной вкладкой.
Как провести первую проверку в продакшене?
Разумный первый тест в производственной среде выполняет одну разрешённую задачу только для чтения и фиксирует её результат независимо от успеха соединения. Используйте короткую продолжительность сессии, явный таймаут задачи и владельца, ответственного за остановку браузера. Сохраните принятый вывод и идентификатор сессии, зачеркивайте учетные данные и проверяйте завершение перед увеличением параллелизма. Это превращает удаленное соединение в рабочий процесс, который вы можете учесть.
Q: Скачивает ли Puppeteer-core браузер для этого примера?
Нет. Пример подключается к существующему удалённому браузеру. Установите основной клиент и предоставьте конечную точку, возвращённую для управляемой сессии.
Q: Нужно ли мне помещать URL CDP в browserURL?
Используйте browserWSEndpoint для возвращаемого URL WebSocket CDP в этом учебном пособии. Не путайте конечную точку WebSocket с URL панели или URL Live View.
Q: Отключение останавливает использование браузера?
Нет. browser.disconnect() оставляет браузер работающим. Остановите сессию Nstdata отдельно и подтвердите её завершённое состояние.
Q: Могу ли я поделиться одним браузером между несвязанными задачами клиентов?
Совместимый браузер может раскрывать состояние и позволять конкурирующим действиям. Назначайте право собственности на сессии и изолируйте несвязанные задачи, а не полагайтесь на порядок вкладок для разделения клиентов.
Q: Гарантирует ли встроенная конфигурация прокси-доступ к сайту?
Нет. Конфигурация прокси предоставляет сетевой путь. Разрешения сайта, требования входа, поведение рендеринга и принятие задач всё ещё требуют независимой проверки.
Q: Что мне делать после того, как соединение потеряно?
Сначала запросите оригинальную сессию. Если она остаётся готовой, запросите свежие учетные данные и заново обнаружьте целевую страницу; если она завершилась, начните новую разрешённую задачу и восстановите только то состояние, которое ваше приложение разрешает повторно использовать.
Пусть оператор войдет через Live View, прежде чем скрипт проверит ту же вкладку приложения. Определите принадлежность, утверждения учетной записи, границы одобрения и очистку, не встраивая пароль в автоматизацию.
Ivy Lin
Nov. 17th 2026
Запускайте облачные браузеры по запросу
Работайте с отпечатками браузера и CAPTCHA
Автоматизируйте процессы и расширяйте возможности ИИ-агентов
От сбора веб-данных и тестирования до автоматизации с ИИ — запускайте всё в облаке.