Cách kết nối Puppeteer với một trình duyệt trên đám mây
TL;DR
Một kết nối trình duyệt từ xa của Puppeteer sử dụng puppeteer.connect() và điểm cuối WebSocket của trình duyệt từ xa.
puppeteer-core là thích hợp khi worker của bạn kết nối đến một trình duyệt mà một dịch vụ khác đã chạy.
Các cuộc gọi HTTP vòng đời Nstdata sử dụng một API khóa kinh doanh; các kết nối CDP sử dụng thông tin xác thực ngắn hạn, được phát hành riêng biệt.
Sử dụng browserWSEndpoint cho URL WebSocket CDP trả về và chuyển thông tin xác thực thông qua tên tiêu đề được trả về.
Đặt defaultViewport: null khi bạn muốn giữ nguyên viewport hiện có của trình duyệt từ xa thay vì áp dụng ghi đè mặc định của Puppeteer.
browser.disconnect() để trình duyệt từ xa tiếp tục chạy; dừng phiên Nstdata riêng biệt sau khi hoàn thành tác vụ.
Kết Nối Trình Duyệt Từ Xa của Puppeteer Là Gì?
Kết nối trình duyệt từ xa của Puppeteer cho phép một client Node.js điều khiển một trình duyệt đã chạy thay vì khởi động một bản thực thi cục bộ. Puppeteer gửi các lệnh tự động hóa qua một kết nối giao thức; trình duyệt thực hiện việc điều hướng, thực thi JavaScript và kết xuất trên máy chủ của nó. Điều này hữu ích khi các worker cần nhỏ gọn hoặc một nhà điều hành cần xem cùng một phiên mà script điều khiển.
Nstdata Cloud Browser cung cấp các trình duyệt đám mây được quản lý cho tự động hóa trình duyệt và các đại lý AI với một bề mặt kết nối CDP. Trong hướng dẫn này, bảng điều khiển sở hữu việc tạo và dừng phiên, trong khi một client Puppeteer nhỏ sở hữu một trang tạm thời. Tách biệt những trách nhiệm đó giúp việc tích hợp đầu tiên dễ dàng kiểm tra hơn.
Ví dụ này xác thực một trang công cộng mà không cần đăng nhập vào tài khoản hay gửi dữ liệu. Để giới thiệu khung rộng hơn, hướng dẫn Node.js Puppeteer và Playwright hiện có đề cập đến tự động hóa trang cục bộ. Bài viết này tập trung vào hợp đồng thêm được giới thiệu bởi một trình duyệt từ xa: danh tính điểm cuối, thời gian tồn tại của thông tin xác thực, quyền sở hữu trang và tắt nguồn.
Nstdata Cloud Browser Trình duyệt của bạn trên đám mây
Bạn Có Nên Sử Dụng Puppeteer Hay Puppeteer-Core?
Sử dụng puppeteer-core khi ứng dụng của bạn cung cấp một điểm cuối trình duyệt có sẵn và không cần tải xuống trình duyệt được quản lý của Puppeteer. Hướng dẫn cài đặt Puppeteer phân biệt gói đầy đủ với thư viện lõi. Việc chọn gói lõi không tạo ra một trình duyệt; một trình duyệt từ xa tương thích phải đã có sẵn.
Quyết Định
Sử Dụng trong hướng dẫn này
Tạo trình duyệt
Nstdata Playground
Gói client
puppeteer-core
Phương thức kết nối
puppeteer.connect()
Tùy chọn điểm cuối
browserWSEndpoint
Quyền sở hữu trang
Tạo và đóng một trang trình diễn
Dọn dẹp được quản lý
Dừng phiên gốc trong bảng điều khiển
Đừng nhầm lẫn việc chạy Puppeteer trên worker Node.js của bạn với việc đóng gói API của nó bên trong một trang web client. Ví dụ này là một script phía server. Các API khóa kinh doanh sẽ ở trong môi trường worker và không bao giờ vào gói JavaScript của một trang web.
Bạn Cần Những Thông Tin Xác Thực và Cài Đặt Nào?
Bạn cần một phiên Cloud Browser sẵn sàng, Node.js 22.12 hoặc mới hơn, và một API khóa kinh doanh cho workspace sở hữu phiên đó. Nhận một khóa cá nhân từ Settings → Account, hoặc sử dụng khóa thành viên từ Members. Kiểm tra số dư workspace hiện tại và phép cho phép đồng thời trước khi khởi chạy.
ID phiên xác định trình duyệt đang chạy. NSTDATA_API_KEY trở thành tiêu đề vòng đời x-api-key mà không có tiền tố Bearer. Một khóa cá nhân có thể chọn một đội đã gia nhập thông qua NSTDATA_TEAM_ID, được gửi dưới dạng x-team-id; một khóa thành viên sử dụng đội đã liên kết của nó. Giữ bối cảnh này giống nhau để tra cứu và phát hành thông tin xác thực.
Điểm cuối thông tin xác thực trả về cdpUrl, headerName, accessToken, và expiresAt cho cùng một phiên. Những giá trị đó xác thực kết nối WebSocket. Chúng không phải là một thay thế có thể tái sử dụng cho API khóa kinh doanh, và một token cũ không làm sống lại một trình duyệt đã kết thúc.
Bắt tay, điều hướng, xác nhận và ngắt kết nối Puppeteer của hướng dẫn này đã được thực hiện chống lại một Chromium cục bộ tách biệt. Nhánh thông tin xác thực tài khoản được quản lý yêu cầu khóa của bạn và không được chạy chống lại một workspace Nstdata có phí. Xem việc thực hiện quản lý đầu tiên của bạn như một canary tích hợp, với việc tắt phiên được bao gồm trong chấp thuận.
Làm Thế Nào Để Kết Nối Puppeteer với Một Cloud Browser?
Kết nối Puppeteer bằng cách khởi động một phiên, cài đặt client lõi, lấy thông tin xác thực cụ thể cho phiên và cung cấp chúng cho puppeteer.connect(). API kết nối Puppeteer là tài liệu tham khảo client cho hoạt động này.
Bước 1: Tạo một phiên từ xa có thể nhìn thấy
Mở Cloud Browser → Playground và chọn không gian làm việc cá nhân hoặc nhóm mong muốn. Đặt Session Name, Proxy Country, Resource Class, và Session Duration, sau đó nhấn Launch Browser. Chờ Running và một bản xem trước có thể sử dụng.
[Ảnh chụp màn hình: Một phiên Cloud Browser đang chạy với không gian làm việc và tên phiên hiển thị; ẩn các liên kết truy cập, token và nội dung trang riêng tư.]
Cấu hình quốc gia proxy trước khi phiên bắt đầu. Khách hàng thừa hưởng đường dẫn mạng đã cấu hình của phiên, vì vậy ví dụ này không truyền một URL proxy thứ hai vào Puppeteer. Quốc gia proxy, ngôn ngữ và múi giờ là những cài đặt khác nhau; việc chọn một quốc gia không đảm bảo địa chỉ cố định hoặc một phiên truy cập trang web được xác thực.
Bước 2: Cài đặt Puppeteer-core
Khởi tạo một dự án và cài đặt phiên bản khách hàng chính xác được sử dụng cho ví dụ. Giữ lại tệp lockfile được tạo để một công nhân khác có thể tái tạo lựa chọn phụ thuộc.
mkdir cloud-puppeteer-demo
cd cloud-puppeteer-demo
npm init -ynpminstall --save-exact puppeteer-core@25.17.0
Bước 3: Lưu trình trợ giúp thông tin xác thực
Lưu mã sau dưới dạng cloud-api.mjs. Nó truy vấn phiên trước khi yêu cầu thông tin xác thực tự động hóa và tạo tiêu đề CDP từ trường được trả về. Khi trường đó là Authorization, giá trị nhận tiền tố Bearer; các tên tiêu đề khác trả về nhận token truy cập thô.
Yêu cầu trước về thông tin xác thực: nhánh Nstdata yêu cầu khóa API doanh nghiệp của bạn và phiên sẵn có. Tùy chọn loopback của trình trợ giúp chỉ tồn tại cho một trình duyệt thử nghiệm cục bộ riêng biệt và phải giữ nguyên trạng thái không thiết lập cho quy trình làm việc được quản lý.
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ụ trình duyệt
Lưu kịch bản này dưới dạng connect-puppeteer.mjs. Nó mở một trang, kiểm tra phản hồi điều hướng, và xác minh tiêu đề mong đợi trước khi đóng trang và ngắt kết nối. Các giá trị timeout ràng buộc bài trình diễn này; chúng không phải là hạn chế dịch vụ.
Yêu cầu trước về thông tin xác thực: thực thi được quản lý yêu cầu khóa và cài đặt môi trường phiên mô tả ở trên. Nhánh khách hàng đã được thực thi thông qua một kết nối CDP cục bộ thực tế.
defaultViewport: null giữ nguyên viewport hiện có thay vì áp dụng mặc định của Puppeteer. Nó không thay đổi dấu vân tay màn hình của phiên, quốc gia proxy, hoặc độ phóng đại của Live View. Nếu nhiệm vụ của bạn cần một viewport đặc biệt, hãy đặt nó một cách có chủ ý và xác minh bố cục đã được hiển thị sau khi gắn kết.
Bước 5: Chạy kiểm tra trang
Tạo một tệp riêng tư .env với NSTDATA_API_KEY và NSTDATA_SESSION_ID, cùng NSTDATA_TEAM_ID chỉ khi cần thiết. Loại bỏ nó khỏi kiểm soát phiên bản. Chạy lệnh sau từ thư mục chứa cả hai mô-đun.
node --env-file=.env connect-puppeteer.mjs
Đối với mục tiêu mặc định, kịch bản in ra một đối tượng JSON với heading: "Example Domain" và taskPassed: true. Một kết nối điểm cuối đơn thuần sẽ không tạo ra xác nhận đó. Nếu bạn tùy chỉnh mục tiêu, hãy cập nhật bộ chọn và giá trị mong đợi cùng nhau; một trang không liên quan có h1 không đủ bằng chứng.
Bước 6: Dừng phiên bạn đã tạo
Nhấn Stop Browser trong phiên gốc và chờ hoàn tất. Phương thức ngắt kết nối Puppeteer giải phóng kết nối khách hàng trong khi vẫn để trình duyệt chạy. Việc tắt trình duyệt được quản lý vẫn là một hành động riêng biệt.
Đối với một công việc thuộc sở hữu API, dừng với DELETE /api/v1/cloud-browser/sessions/{sessionId} và kiểm tra cho đến khi state là ended. Một sự cố của worker có thể bỏ qua dọn dẹp thông thường, vì vậy hãy giữ ID phiên bên ngoài bộ nhớ quy trình tạm thời. Sử dụng chu trình tự động hóa Trình duyệt hiện tại khi thực hiện dịch vụ sở hữu đó.
Nstdata có thể hỗ trợ quy trình Puppeteer ngoài bản demo như thế nào?
Nstdata Cloud Browser cung cấp trình duyệt được lưu trữ trong khi Puppeteer giữ quyền kiểm soát điều hướng và tương tác trang. Một lập trình viên có thể gắn một kịch bản từ một trình chạy công việc hiện có mà không cần triển khai Chromium trên mỗi worker. Một nhà điều hành có thể kiểm tra cùng một trình duyệt đang chạy khi một nhiệm vụ cần được chú ý. Cấu hình phiên cung cấp một điểm khởi đầu có kiểm soát cho tài nguyên và vị trí proxy. Ứng dụng vẫn quyết định trang nào là hợp lệ, đầu ra nào là chấp nhận được, và khi nào phiên nên dừng lại.
Thời gian chạy trình duyệt được quản lý: di chuyển việc thực thi trình duyệt ra khỏi triển khai worker, sau đó kiểm tra các thao tác Puppeteer cụ thể của bạn so với thời gian chạy đó.
Cấu hình proxy tích hợp sẵn: chọn quốc gia proxy được hỗ trợ của phiên mà không cần duy trì một gateway proxy riêng biệt trong ví dụ khách hàng; theo dõi chi phí lưu lượng truy cập kết quả.
Live View và chẩn đoán: quan sát việc kết xuất và kiểm tra thông tin Console hoặc Network có sẵn khi một trang chờ thất bại.
Chu trình rõ ràng: sử dụng trạng thái phiên để phân biệt các vấn đề kết nối với một trình duyệt đã hết hạn hoặc đã dừng.
Xem lại giá sử dụng Cloud Browser trước khi mở rộng. Thời gian chạy, lưu lượng proxy, và việc sử dụng CAPTCHA tùy chọn là các thành phần chi phí riêng biệt; một kết nối từ xa không phải là một thay thế chi phí cố định cho công việc trình duyệt không giới hạn. Giới thiệu sản phẩm Cloud Browser mô tả ranh giới sản phẩm, và hướng dẫn thực hành Playwright cung cấp một cách tiếp cận bổ sung cho thiết kế nhiệm vụ trình duyệt.
Làm thế nào bạn có thể tái sử dụng một tab hiện có mà không mất trạng thái?
Tái sử dụng một tab hiện có bằng cách xác định nó trong cùng một phiên thay vì tạo một trình duyệt mới hoặc chọn mục đầu tiên trong browser.pages(). Liệt kê các trang có sẵn, khớp một nguồn gốc và đường dẫn mong đợi, và yêu cầu chính xác một ứng viên. Sau đó, xác minh một dấu hiệu tài khoản hoặc không gian làm việc cụ thể của ứng dụng trước khi đọc dữ liệu hoặc nhấp vào các điều khiển.
Bản demo cố ý sử dụng newPage() vì nó không có trạng thái đã đăng nhập để bảo tồn. Một chuyển giao giữa người có hợp đồng khác: không điều hướng tab đã chọn trở lại URL đăng nhập, tạo một ngữ cảnh ẩn danh, hoặc giả định một phiên mới chứa cookie của phiên cũ. Một ứng dụng cũng có thể làm không hợp lệ phiên đăng nhập của nó độc lập với vòng đời của trình duyệt.
Tại Sao Trình Duyệt Kết Nối Nhưng Nhiệm Vụ Thất Bại?
Trình duyệt có thể kết nối thành công trong khi trang đã chọn bị điều hướng, không hoàn chỉnh, đã đăng xuất, hoặc khác với ứng dụng mong đợi. Chẩn đoán lớp nhiệm vụ sau khi kiểm tra lớp kết nối.
Triệu chứng
Nguyên nhân cần điều tra
Sửa lỗi
Yêu cầu xác thực thất bại
Khóa API hoặc sự không tương thích của nhóm
Giữ xác thực kinh doanh và ngữ cảnh không gian làm việc nhất quán
WebSocket từ chối xác thực
Mã thông báo CDP hết hạn hoặc áp dụng sai
Yêu cầu thông tin xác thực mới cho phiên sẵn sàng cùng
Tiêu đề bị thiếu
Điều hướng hoặc hiển thị không đạt đến trạng thái mong đợi
Kiểm tra phản hồi, URL trang một cách riêng tư, và một dấu hiệu sẵn sàng cụ thể
Một đăng nhập hiện tại vắng mặt
Tab/ngữ cảnh mới hoặc phiên trình duyệt sai
Chọn phiên gốc và trang dự định
Trình duyệt vẫn trong lịch sử như đang hoạt động
Khách hàng ngắt kết nối mà không dừng lại
Dừng thông qua chủ sở hữu vòng đời và xác nhận ended
Đừng thêm giấc ngủ tùy tiện trước khi kiểm tra những điều kiện này. Chờ đợi phần tử hoặc phản hồi cụ thể chứng minh sự sẵn sàng. Thời gian chờ lâu chỉ làm chậm một thất bại khi kịch bản đang theo dõi tab sai.
Nên kiểm tra gì trong lần chạy đầu tiên ở môi trường production?
Một bài kiểm tra sản xuất đầu tiên hợp lý thực hiện một nhiệm vụ được ủy quyền, chỉ đọc và ghi lại kết quả của nó độc lập với sự thành công của kết nối. Sử dụng thời gian phiên ngắn, thời gian chờ nhiệm vụ rõ ràng, và một chủ sở hữu chịu trách nhiệm dừng trình duyệt. Giữ kết quả được chấp nhận và ID phiên, bỏ qua thông tin xác thực, và xác minh việc tắt máy trước khi tăng cường độ đồng thời. Điều này biến kết nối từ xa thành một quy trình hoạt động mà bạn có thể tính toán.
Q: Có phải Puppeteer-core tải về một trình duyệt cho ví dụ này không?
Không. Ví dụ kết nối với một trình duyệt từ xa đã tồn tại. Cài đặt client core và cung cấp endpoint trả về cho phiên được quản lý.
Q: Tôi nên đặt URL CDP vào browserURL không?
Sử dụng browserWSEndpoint cho URL WebSocket CDP trả về trong hướng dẫn này. Đừng hoán đổi một endpoint WebSocket với một trang dashboard hoặc URL Live View.
Q: Ngắt kết nối có dừng việc sử dụng trình duyệt không?
Không. browser.disconnect() để trình duyệt chạy. Dừng phiên Nstdata riêng biệt và xác nhận trạng thái đã dừng của nó.
Q: Tôi có thể chia sẻ một trình duyệt giữa các công việc khách hàng không liên quan không?
Một trình duyệt chia sẻ có thể phơi bày trạng thái và cho phép các hành động đối kháng. Giao quyền sở hữu phiên và cách ly các công việc không liên quan thay vì dựa vào thứ tự tab để phân tách khách hàng.
Q: Cấu hình proxy tích hợp có đảm bảo truy cập vào website không?
Không. Cấu hình proxy cung cấp một đường dẫn mạng. Quyền truy cập website, yêu cầu đăng nhập, hành vi hiển thị, và việc chấp nhận nhiệm vụ vẫn cần có các kiểm tra độc lập.
Q: Tôi nên làm gì sau khi kết nối bị ngắt?
Hỏi phiên gốc trước tiên. Nếu nó vẫn sẵn sàng, yêu cầu thông tin xác thực mới và rediscover trang dự định; nếu nó đã kết thúc, bắt đầu một nhiệm vụ được ủy quyền mới và chỉ phục hồi trạng thái mà ứng dụng của bạn được phép tái sử dụng.
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.