Cách kết nối Playwright với trình duyệt từ xa bằng CDP
TL;DR
Playwright kết nối với trình duyệt Chromium hiện có bằng chromium.connectOverCDP(); launch() khởi động một trình duyệt khác.
Một phiên được quản lý phải ở trạng thái ready trước khi bạn yêu cầu thông tin xác thực CDP ngắn hạn và kết nối máy khách.
Khóa API vòng đời và mã thông báo truy cập CDP xác thực các kết nối khác nhau và không thể thay thế cho nhau.
Một lần bắt tay WebSocket thành công chứng minh khả năng kết nối; một khẳng định trang chứng minh rằng nhiệm vụ của bạn đã đạt được kết quả mong đợi.
Sử dụng lại một tab đã đăng nhập hiện có yêu cầu chọn trang rõ ràng trong cùng một phiên đang chạy.
Ngắt kết nối Playwright không xác nhận rằng trình duyệt được quản lý đã dừng; dừng phiên riêng biệt và xác minh ended.
Kết nối Playwright qua CDP hoạt động như thế nào?
Playwright connect over CDP gắn chương trình Node.js của bạn với trình duyệt Chromium đang chạy thông qua Giao thức DevTools của Chrome. Kịch bản chạy trên máy tính xách tay hoặc máy chủ của bạn; trình duyệt hiển thị các trang và thực hiện các yêu cầu trang web trên máy chủ từ xa. Do đó, một điểm cuối được lưu trữ loại bỏ nhu cầu cài đặt tệp nhị phân trình duyệt trên máy chủ đó, trong khi vẫn để selectors, assertions, và quyết định nhiệm vụ trong mã của bạn.
Nstdata Cloud Browser cung cấp trình duyệt đám mây được quản lý cho tự động hóa trình duyệt và các tác nhân AI. Hướng dẫn này sử dụng một phiên được tạo ra từ bảng điều khiển để bạn có thể quan sát trình duyệt trong khi chứng minh kết nối. Nhiệm vụ cuối cùng mở một trang ví dụ công khai, kiểm tra phản hồi HTTP của nó và xác minh tiêu đề của nó. Không có gì được gửi đến một tài khoản hoặc biểu mẫu.
Sự khác biệt rất quan trọng khi mở rộng một luồng công việc web scraping Playwright hiện có: thay thế kết nối trình duyệt một cách có chủ ý, sau đó kiểm tra lựa chọn ngữ cảnh và dọn dẹp. Sao chép một điểm cuối từ xa vào cấu hình khởi động cục bộ không tạo ra cùng một mô hình thực thi.
Nstdata Cloud Browser Trình duyệt của bạn trên đám mây
Nên chọn phương thức kết nối Playwright nào?
Sử dụng connectOverCDP() cho một điểm cuối CDP Chromium, connect() cho một máy chủ Playwright tương thích, và launch() khi ứng dụng của bạn sở hữu một quy trình trình duyệt cục bộ. Những phương thức này diễn đạt các hợp đồng máy chủ khác nhau. API Playwright BrowserType xác định CDP là chỉ dành cho Chromium và có độ trung thực thấp hơn so với giao thức Playwright gốc.
Phương thức
Bề mặt từ xa
Điểm khởi đầu thích hợp
chromium.launch()
Một trình duyệt nhị phân được khởi động bởi mã của bạn
Phát triển cục bộ và một trình duyệt mà bạn điều hành
chromium.connect()
Một điểm cuối máy chủ trình duyệt Playwright
Một triển khai máy chủ/khi khách hàng Playwright được kiểm soát
chromium.connectOverCDP()
Một điểm cuối CDP Chromium
Một trình duyệt hiện có hoặc phiên được quản lý tương thích
Tính tương thích CDP không hứa hẹn hành vi giống hệt cho mỗi tính năng Playwright nâng cao. Kiểm tra các hoạt động mà ứng dụng của bạn thực sự cần so với trình duyệt được quản lý. Việc điều hướng cơ bản không đảm bảo rằng tracing, luồng mở rộng, tải xuống, hoặc mọi tùy chọn ngữ cảnh hoạt động giống như một trình duyệt được khởi động cục bộ.
Cần chuẩn bị gì trước khi kết nối?
Bạn cần Node.js 22.12 trở lên, playwright-core, một không gian làm việc Nstdata có thể truy cập, một phiên sẵn sàng, và khóa API kinh doanh đúng. Lấy khóa cá nhân dưới Settings → Account, hoặc khóa thành viên đội dưới Members. Xác nhận số dư không gian làm việc và hạn mức đồng thời hiện tại trước khi khởi động một trình duyệt.
Trường
Nguồn gốc
Nơi thuộc về
NSTDATA_API_KEY
Khóa tài khoản hoặc nhóm của bạn
Header HTTP vòng đời x-api-key, không có Bearer
NSTDATA_TEAM_ID
Một nhóm đã tham gia, khi sử dụng khóa cá nhân
Tùy chọn x-team-id trên mỗi yêu cầu vòng đời
NSTDATA_SESSION_ID
Phiên bạn đã khởi động
Đường dẫn tìm kiếm phiên và thông tin xác thực
cdpUrl
Phản hồi thông tin xác thực tự động
Tham số điểm cuối connectOverCDP()
headerName, accessToken
Phản hồi thông tin xác thực giống nhau
Header kết nối CDP
expiresAt
Phản hồi thông tin xác thực giống nhau
Kiểm tra hết hạn trước khi gắn
Khóa thành viên đội bị ràng buộc với đội của nó; việc thêm một ID đội khác không thay đổi nó. Giữ ngữ cảnh không gian làm việc đồng nhất trong suốt quy trình làm việc. Không sử dụng JWT đăng nhập bảng điều khiển như khóa API kinh doanh.
Khách hàng bên dưới đã được thử nghiệm thông qua một kết nối CDP thực tế đến một trình duyệt Chromium cục bộ mới, tách biệt. Nhánh thông tin xác thực Nstdata yêu cầu khóa API của bạn và không được thực hiện với một tài khoản trả phí. Việc thực thi cục bộ xác minh các hoạt động của khách hàng; nó không thiết lập xác thực tài khoản được quản lý hoặc hành vi thanh toán.
Làm thế nào để kết nối Playwright với Nstdata Cloud Browser?
Kết nối bằng cách tạo một phiên hiển thị, truy xuất thông tin đăng nhập cho phiên đó và truyền các thông tin đăng nhập đó cho Playwright. Hướng dẫn Tự động hóa trình duyệt hiện tại tài liệu về vòng đời và sự phân tách thông tin đăng nhập được sử dụng bên dưới.
Bước 1: Khởi động một phiên trình duyệt
Mở Cloud Browser → Playground, chọn không gian làm việc mong muốn, và cấu hình Session Name, Proxy Country, Resource Class, và Session Duration. Nhấp vào Launch Browser. Chờ cho đến khi khu vực công cụ cho thấy Running và bản xem trước có sẵn.
[Screenshot: Playground showing a running session and the CDP tools area, with all access URLs and tokens hidden.]
Chọn các cài đặt proxy và môi trường trước khi khởi động. Quốc gia proxy chọn một vị trí thoát; nó không hứa hẹn một IP cố định. Thời gian phiên là một giới hạn tuổi thọ tự động, khác với thời gian chờ điều hướng trong tập lệnh của bạn.
Bước 2: Cài đặt phụ thuộc của khách hàng
Tạo một thư mục dự án và cài đặt phiên bản được sử dụng cho ví dụ này. playwright-core cung cấp khách hàng mà không cần tải xuống một trình duyệt cho người làm việc.
mkdir remote-playwright-demo
cd remote-playwright-demo
npm init -ynpminstall --save-exact playwright-core@1.65.1
Bước 3: Lưu trợ giúp kết nối
Lưu mô-đun sau đây dưới dạng cloud-api.mjs. Nó tra cứu phiên gốc, yêu cầu state === 'ready', yêu cầu thông tin đăng nhập và xác thực danh tính và thời gian hết hạn của phiên được trả về. Nhánh chỉ vòng lặp là cho trình duyệt kiểm tra nhà phát triển được tách biệt; sản xuất theo nhánh thông tin đăng nhập Nstdata.
Điều kiện tiên quyết cho thông tin đăng nhập: Các yêu cầu API Nstdata trong mô-đun này yêu cầu khóa của bạn, ID phiên, và ngữ cảnh nhóm tùy chọn. Cung cấp chúng cục bộ; không bao giờ dán giá trị thực của chúng vào kiểm soát nguồn hoặc nhật ký chia sẻ.
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);}
Bước 4: Lưu tác vụ xác minh trang
Lưu tập lệnh này dưới dạng connect-playwright.mjs. Tập lệnh tạo một trang bên trong ngữ cảnh mặc định và chỉ đóng trang đó trước khi giải phóng khách hàng. Đọc các ngữ nghĩa dọn dẹp trình duyệt kết nối trước khi điều chỉnh dọn dẹp cho một phiên chia sẻ.
Điều kiện tiên quyết cho thông tin đăng nhập: con đường thực thi được quản lý yêu cầu các cài đặt môi trường từ Bước 3. Logic trang và bắt tay CDP thực tế đã được xác minh cục bộ.
import{ chromium }from'playwright-core';import{ endpoint }from'./cloud-api.mjs';asyncfunctionmain(){const config =awaitendpoint();let browser;let page;try{ browser =await chromium.connectOverCDP(config.endpoint,{headers: config.headers,timeout:30_000,});const context = browser.contexts()[0];if(!context)thrownewError('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())thrownewError('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;});
Bước 5: Chạy bài kiểm tra kết nối
Tạo một tệp riêng tư .env chứa NSTDATA_API_KEY và NSTDATA_SESSION_ID, với các giá trị thực của bạn sau dấu =. Thêm NSTDATA_TEAM_ID chỉ khi áp dụng. Loại trừ tệp này khỏi kiểm soát phiên bản, sau đó chạy lệnh bên dưới. Để LOCAL_CDP_URL không được thiết lập cho phiên làm việc quản lý.
node --env-file=.env connect-playwright.mjs
Đối với mục tiêu mặc định, thành công là một đối tượng JSON chứa connected: true, heading: "Example Domain", và taskPassed: true. Bộ chọn căn cứ vào vai trò kiểm tra kết quả trang thay vì coi một socket đã kết nối như là hoàn thành nhiệm vụ. Nếu bạn thay đổi TARGET_URL, hãy thay đổi câu khẳng định cho phù hợp với trang được ủy quyền dự kiến.
Bước 6: Dừng phiên quản lý
Quay lại phiên gốc và nhấp vào Stop Browser. Chờ phiên hoàn thành. Trong một công việc do API sở hữu, gọi DELETE /api/v1/cloud-browser/sessions/{sessionId} và lấy polling cho phiên đó cho đến khi trạng thái của nó là ended. Đóng tab xem trước hoặc giải phóng Playwright không phải là thao tác dừng này.
Cloud Browser phù hợp với quy trình Playwright trong môi trường production như thế nào?
Nstdata Cloud Browser phù hợp với quy trình làm việc Playwright khi nhóm của bạn muốn thực thi trình duyệt được quản lý với các điều khiển phiên có thể thấy. Ứng dụng của bạn vẫn sở hữu nhiệm vụ, sơ đồ đầu ra và tiêu chí chấp nhận. Dịch vụ này cung cấp phiên trình duyệt từ xa và bề mặt kết nối của nó. Trình duyệt đang chạy cùng một có thể được xem theo cách thủ công và điều khiển qua CDP. Điều đó làm cho một nhiệm vụ thất bại có thể kiểm tra mà không cần giả định rằng kịch bản đã chọn đúng trang hoặc tài khoản.
Thực thi được quản lý: gắn một khách hàng từ một nhân viên không mang theo cài đặt Chromium riêng của nó; giữ lại thời gian chờ và khẳng định cấp ứng dụng.
Cấu hình proxy cấp phiên: sử dụng cấu hình proxy tích hợp sẵn đã chọn mà không thêm một cổng proxy riêng cho kịch bản khách hàng này; đo lường lưu lượng proxy cùng với thời gian chạy trình duyệt.
Kiểm tra trực tiếp: quan sát trang đang hoạt động và các chẩn đoán có sẵn khi một bộ chọn thất bại; kiểm tra không tự động sửa chữa logic ứng dụng.
Một kết nối CDP thất bại khi điểm cuối, thông tin xác thực, trạng thái phiên hoặc đường dẫn mạng không hợp lệ; trang sai thường chỉ ra rằng ngữ cảnh hoặc lựa chọn tab không chính xác.
Triệu chứng
Nguyên nhân có thể
Hành động tiếp theo
Xác thực HTTP vòng đời thất bại
Khóa sai hoặc ngữ cảnh nhóm sai
Kiểm tra x-api-key và x-team-id nhất quán
Ủy quyền CDP thất bại
Mã thông báo đã hết hạn hoặc tiêu đề không chính xác
Truy vấn phiên sẵn sàng tương tự và yêu cầu thông tin xác thực mới
Trình duyệt kết nối nhưng ứng dụng đã đăng xuất
Một trang/nhân контекст mới hoặc phiên khác đã được sử dụng
Chọn tab ủy quyền hiện có một cách cụ thể
Thời gian chờ xác nhận tiêu đề
Trang sai, chuyển hướng, hoặc nội dung đã thay đổi
Kiểm tra trang đã chọn và dấu hiệu mong đợi
Phiên ended
Thời gian sống đã hết hoặc trình duyệt đã dừng
Bắt đầu một tác vụ mới cố ý; không sử dụng lại thông tin xác thực cũ
Tránh việc khởi động lại toàn bộ công việc để khắc phục sự cố xác thực. Một ID phiên mới có thể ẩn đi sự thất bại ban đầu và tạo ra thêm việc sử dụng thời gian chạy. Giữ các định danh yêu cầu/phiên trong nhật ký vận hành, đồng thời biên tập các mã thông báo truy cập và URL CDP hoàn chỉnh.
Cần kiểm tra gì trước khi triển khai tích hợp?
Kiểm tra kết nối được quản lý, tác vụ trang thực tế và sự đóng phiên đã xác nhận như là các kiểm tra riêng biệt. Chạy một canary sản xuất hẹp với không gian làm việc và mục tiêu dự kiến, ghi lại ID phiên và đầu ra được chấp nhận của nó, và xác nhận ended sau đó. Mở rộng chỉ sau khi các tương tác cần thiết của bạn hoạt động với trình duyệt từ xa. Điều này mang lại cho nhóm một bài kiểm tra chấp nhận có thể lặp lại thay vì một buổi trình diễn chỉ với kết nối.
Q: Liệu Playwright có thể kết nối qua CDP tới Firefox hoặc WebKit không?
Không. Kết nối CDP của Playwright chỉ dành cho các trình duyệt dựa trên Chromium. Sử dụng quy trình trình duyệt hỗ trợ phù hợp khi bài kiểm tra của bạn yêu cầu Firefox hoặc WebKit.
Q: Tôi có cần cài đặt Chromium trên worker không?
Không cần tệp nhị phân trình duyệt cho ví dụ kết nối từ xa này. Cài đặt playwright-core trên worker và kết nối với trình duyệt đang chạy trong phiên được quản lý.
Q: Liệu tập lệnh khởi động nhanh có tái sử dụng tab đã đăng nhập của tôi không?
Không. Tập lệnh này tạo một trang mới. Đối với việc chuyển giao đăng nhập thủ công, hãy chọn trang hiện có theo nguồn, đường dẫn, và dấu hiệu tài khoản dự kiến trong cùng một phiên đang chạy.
Q: Tôi có thể sử dụng khóa API doanh nghiệp làm mã thông báo CDP không?
Không. Sử dụng khóa doanh nghiệp cho các yêu cầu vòng đời, sau đó lấy accessToken và headerName có thời gian sống ngắn từ phản hồi automation-credentials.
Q: Việc ngắt kết nối có đặt lại thời gian phiên không?
Không. Kết nối lại một khách hàng không kéo dài thời gian sống của phiên được quản lý. Truy vấn trạng thái ban đầu trước khi yêu cầu thông tin xác thực mới.
Q: Kiểm tra tiêu đề thành công có đủ cho sản xuất không?
Kiểm tra tiêu đề là đủ cho màn trình diễn kết nối này. Các tác vụ sản xuất cần có tiêu chí chấp nhận riêng, xử lý lỗi, và xác nhận dọn dẹp, chỉ sử dụng các trang web và tài khoản mà bạn được ủy quyền tự động hóa.
Hãy để một người điều hành đăng nhập qua Live View trước khi một kịch bản xác minh cùng một tab ứng dụng. Định nghĩa quyền sở hữu, xác nhận tài khoản, ranh giới phê duyệt và dọn dẹp mà không nhúng mật khẩu vào quá trình tự động hóa.
Ivy Lin
Nov. 17th 2026
Khởi chạy trình duyệt đám mây theo nhu cầu
Xử lý dấu vân tay trình duyệt và CAPTCHA
Tự động hóa quy trình và hỗ trợ tác nhân AI
Từ thu thập dữ liệu web và kiểm thử đến tự động hóa bằng AI, vận hành tất cả trên đám mây.