Nstproxy 现已升级为 Nstdata。了解此次变化。
周一至周五 09:00 - 18:00(UTC+08:00) 公司地址
19H MAXGRAND PLAZA NO.3 TAI YAU STREET SAN PO KONG, KOWLOON HONG KONG ©2026 NST LABS TECH LTD. 保留所有权利。
Ivy Lin Community & Content Lead
如何通过控制台和网络日志调试浏览器自动化 TL;DR
浏览器自动化调试应该分离会话连接、页面选择、网络传输、渲染和任务接受。
控制台消息描述了页面活动;HTTP错误响应和传输失败需要不同的事件处理程序。
在导航或您想要诊断的操作之前安装编程监听器。
在仪表板开发者工具中选择页面并不会在您的自动化脚本中选择该页面。
实时检查显示正在运行的浏览器;归档会话回放重建记录的页面更改,无法操作浏览器。
绑定和遮盖诊断,并在调查后停止会话,因为调试可能继续消耗运行时间。
浏览器自动化调试应该告诉你什么?
浏览器自动化调试应该告诉你哪个层次失败以及什么证据支持该结论。连接的客户端只建立到浏览器的传输。由于选择了错误的页面、应用请求返回了错误、JavaScript崩溃或准备选择器不再匹配预期视图,任务仍然可能失败。
Nstdata Cloud Browser 提供用于浏览器自动化和带有实时浏览器检查与可用会话诊断的 AI 代理的托管云浏览器。本指南结合了该仪表板视图和受限的 Playwright 日志捕获。其目的是在不将整个私密浏览会话收集到票证中的情况下识别失败的步骤。
Playwright 互动教程 介绍了任务级别的页面检查。在这里,接受条件是明确的:主文档必须成功,并且配置的准备标记必须变为可见。控制台和网络证据解释失败,但不能替代该条件。
您如何决定首先检查哪个层次?
检查最早失败的前提条件:会话状态、客户端连接、预期页面、关键请求,然后是渲染结果。这个顺序避免了在浏览器已经结束时重写选择器,或者将成功的套接字解释为已完成的业务操作。
观察 要检查的层 有用证据 无法附加到 CDP 资源或连接 原始会话状态、凭证过期、客户端超时 浏览器已连接,但视图意外 页面身份 预期来源/路径、账户标记、活动文档 视图加载但数据缺失 网络/应用 所需请求的HTTP状态或传输失败 页面变为空白或不完整 渲染 页面异常、可用 DOM、失败的脚本/资源 任务报告成功不正确 接受逻辑 所需结果标记和预期输出
主文档可以返回成功的响应,而API请求随后失败。可见的头部可以出现在您的任务需要的记录之前。根据应用行为设计预期结果,然后收集足够的证据以区分这些情况。不要将每个控制台警告转换为失败的工作。
捕获诊断之前需要什么?
您需要一个授权目标、一个可重现的任务、一个精确的准备选择器,以及从该页面保留诊断数据的权限。使用具有合成内容的预发布应用进行第一次运行。保持您的 Nstdata 会话 ID 和作业 ID 可用,但从日志中排除 API 密钥、CDP 令牌和完整的已签名访问 URL。
对于编程方法,安装 Node.js 22.12 或更高版本和 playwright-core。通过 Settings → Account 获取商业 API 密钥,或者通过 Members 获取绑定团队成员密钥。如果个人密钥选择了团队,则在所有生命周期调用中发送相同的可选团队上下文。
本文的客户端捕获是通过针对一个故意发出控制台警告、JavaScript 异常、HTTP 错误和失败连接的隔离本地页面通过真实的 CDP 连接执行的。Nstdata 凭证分支需要您的密钥,并且未在托管账户上运行。展示的事件类型是固定观察,而不是服务性能声明。
如何在仪表板中检查正在运行的浏览器?
步骤 1:打开原始运行会话 打开 Cloud Browser → Playground 并选择您作业使用的会话。在故障排除其页面之前确认 Running 。如果资源已结束,实时检查无法重新连接;请使用可用历史记录或启动故意新的重现。
步骤 2:连接检查工具 点击右上角预览工具区域的 DevTools 。如果该区域被折叠,请使用 Expand Tools 。等待 Connected 然后选择所需的 Page 。所选页面会更改检查目标,而不是脚本的页面变量。
[Screenshot: Live DevTools connected to the selected staging page, with Console and Network tabs visible and all access credentials hidden.]
第 3 步:检查相关面板 使用 Elements 查看只读的 HTML 快照,使用 Console 查看新接收的消息和异常,使用 Network 查看方法、状态或失败原因、URL、MIME 类型和可用的已清理标题。在适当情况下,附加工具后重现狭窄的失败操作;不要假设检查器包含连接之前的每个事件。
如果该元素仅存在于帧内,请检查正确的文档并调整脚本的帧选择。如果应用程序已注销,请修复会话转移,而不是延长元素的超时。在它们的证据可以进行比较之前,仪表板和脚本必须就页面身份达成一致。
如何在 Playwright 中采集控制台和网络诊断信息? 通过在导航前注册边界监听器并在页面任务后编写结构化报告来捕获证据。Playwright 网络指南 涵盖了请求和响应观察。此示例保留事件元数据,并故意省略原始标题、页面主体、完整 URL 和控制台消息文本。
第 1 步:安装捕获客户端 创建一个项目并安装此处使用的确切 Playwright 客户端版本。远程连接不需要在此工作者上拥有 Chromium 二进制文件。
mkdir browser-debug-demo
cd browser-debug-demo
npm init -y
npm install --save-exact playwright-core@1.65.1
第 2 步:保存连接助手 将该模块保存为 cloud-api.mjs。它在不记录任何访问令牌的情况下验证会话和短期凭据响应。在使用 Nstdata 时,保持其环回测试选项未设置。
凭证前提: 管理请求需要 NSTDATA_API_KEY、NSTDATA_SESSION_ID 和可选的 NSTDATA_TEAM_ID。连接和捕获逻辑在本地进行了测试;管理身份验证仍然需要一个帐户识别。
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 ) ;
}
第 3 步:保存绑定捕获脚本 将此代码保存为 debug.mjs。它创建一个页面,在导航之前附加监听器,并将结果记录到 browser-debug.json。事件上限和超时是示例应用程序的保护措施,而不是 Nstdata 的限制。
凭据前提条件: 被管理的分支需要助手的帐户设置。为授权应用程序设置 TARGET_URL 和 READY_SELECTOR;对于任意网站没有通用的准备就绪选择器。
import { chromium } from 'playwright-core' ;
import { writeFile } from 'node:fs/promises' ;
import { endpoint } from './cloud-api.mjs' ;
async function main ( ) {
if ( ! process . env . TARGET_URL || ! process . env . READY_SELECTOR ) {
throw new Error ( 'Set TARGET_URL and READY_SELECTOR' ) ;
}
const target = new URL ( process . env . TARGET_URL ) ;
const config = await endpoint ( ) ;
const browser = await chromium . connectOverCDP ( config . endpoint , { headers : config . headers } ) ;
const events = [ ] ;
const add = record => { if ( events . length < 200 ) events . push ( { at : new Date ( ) . toISOString ( ) , ... record } ) ; } ;
// Retain only a caller-approved origin; omit paths, query strings, and fragments.
const originLabel = value => {
try { return new URL ( value ) . origin === target . origin ? 'target-origin' : 'other-origin' ; }
catch { return 'unknown-origin' ; }
} ;
let page ;
let passed = false ;
try {
const context = browser . contexts ( ) [ 0 ] ;
if ( ! context ) throw new Error ( 'Missing default context' ) ;
page = await context . newPage ( ) ;
page . on ( 'console' , message => add ( { kind : 'console' , level : message . type ( ) } ) ) ;
page . on ( 'pageerror' , ( ) => add ( { kind : 'pageerror' } ) ) ;
page . on ( 'response' , response => {
if ( response . status ( ) >= 400 ) add ( { kind : 'http-error' , status : response . status ( ) ,
origin : originLabel ( response . url ( ) ) , resource : response . request ( ) . resourceType ( ) } ) ;
} ) ;
page . on ( 'requestfailed' , request => add ( { kind : 'transport-error' ,
method : request . method ( ) , origin : originLabel ( request . url ( ) ) , resource : request . resourceType ( ) } ) ) ;
const response = await page . goto ( target . href , { waitUntil : 'domcontentloaded' , timeout : 30_000 } ) ;
if ( ! response ?. ok ( ) ) throw new Error ( 'Main document failed' ) ;
await page . locator ( process . env . READY_SELECTOR ) . waitFor ( { state : 'visible' , timeout : 15_000 } ) ;
passed = true ;
} catch {
add ( { kind : 'task-failed' } ) ;
process . exitCode = 1 ;
} finally {
try { if ( page ) await page . close ( ) ; }
finally {
try { await browser . close ( ) ; }
finally {
await writeFile ( 'browser-debug.json' , JSON . stringify ( { taskPassed : passed , events } , null , 2 ) , { mode : 0o600 } ) ;
}
}
}
}
main ( ) . catch ( ( ) => {
console . error ( "Browser task failed; inspect private diagnostics and the original session." ) ;
process . exitCode = 1 ;
} ) ;
Playwright 请求事件生命周期 区分了 HTTP 错误响应与无法完成的请求。404或503仍然是 HTTP 响应,因此请检查 response 状态。传输失败通过 requestfailed 显示。该脚本保持这些类别独立,而不是将它们计为同一错误。
步骤 4:运行一个可重现的任务 创建一个私有的 .env 文件,其中包含密钥、会话 ID、授权的 TARGET_URL 和一个选择器,以证明所需内容已经准备好。仅在必要时添加团队上下文,然后从项目目录运行脚本。
node --env-file = .env debug.mjs
单独从事件列表中读取 taskPassed。一个页面可能满足所选标记,而一个不相关的图像返回错误。相反,如果标记从未出现,则空事件列表并不能证明成功。在此示例中,缺少标记或主要文档失败会产生非零退出代码和一个 task-failed 记录。
报告故意分组来源,而不是存储完整 URL。如果您需要识别特定的端点,请添加经过审查的白名单,将已知安全路径映射到稳定标签。不要简单启用原始请求日志记录:查询字符串和路径段可能包含机密或个人标识符。
步骤 5:停止调试会话 单击 Stop Browser ,并在收集所需证据后确认原始会话已结束。脚本关闭其自己的页面并释放 Playwright;它不会终止仪表板拥有的管理会话。仅在您的调查需要的时间内保留报告。
Nstdata 如何将实时检查与会话历史连接起来? Nstdata Cloud Browser 将实时检查与历史记录连接起来,通过为运行中的浏览器和启用录制时的记录观察提供工具。开发人员可以在保持现有 Playwright 任务逻辑的同时观察远程页面。会话身份帮助将失败的任务与操作员正在检查的浏览器相关联。内置的代理配置仍然是该会话的一部分,而不是单独的客户端设置。您的应用程序仍然负责数据修订、任务接受和业务错误的诊断。
实时浏览器可见性: 在更改选择器之前,比较实际远程视图与脚本的预期页面。
控制台和网络检查: 确定选定文档的新接收错误和请求结果。
可选录制: 在启动前启用录制时,保留可用的页面观察以供后续调查。
管理的会话控制: 明确停止调查的资源,而不是让未连接的浏览器处于活动状态。
浏览器停止后如何回顾已录制的故障过程? 通过 Cloud Browser → Session History → session name 查看录制的失败,前提是启用了录制且相关数据仍然可用。启动前启用 Session Recording 以便稍后检查的再现。在停止后,等待归档,而不是假设录制可以立即读取。
选择 Replay Page 以获取预期的录制文档,然后使用 Play 、时间线和播放速度来定位失败的步骤。重放 DevTools 显示所选页面和播放位置的保存信息。每个文档都有自己的时间线;不要从单独的播放视图推断同步的跨标签顺序。
重放重建录制的页面变化,而不是播放 MP4 或重新运行应用程序。在重建过程中不会加载脚本和外部资源,因此图像、字体和画布可能会有所不同。存档的 ready 状态意味着可读取的数据,而 partial 表示不完整的存档数据;两者都不保证每个页面都有可用的快照。缺失、过期或未录制的数据无法通过重放恢复。
在添加重试之前应修复什么? 在添加重试之前修复页面身份、关键请求处理和接受逻辑。针对错误标签的重试会重复错误的任务,而在不确定的提交后进行重试可能会重复一个操作。重现最小的授权步骤,分类其失败,并选择一种有界响应,尊重可能已经完成的操作。
保持诊断与调查相称。OWASP 记录指导 在决定哪些字段要排除时非常有用。单靠输入屏蔽并不删除网站打印的私密页面文本或数据。修复经过验证后,在关闭事件之前确认预期的任务结果和会话关闭。
FAQ Q: HTTP 404 是否触发 requestfailed?
HTTP 404 是一种响应,因此通过响应监听器处理其状态。对于未能在传输层完成的请求,请使用 requestfailed。
实时检查和新附加的监听器可能只能观察到连接后接收到的消息。在重现失败操作之前附加,或者使用可用的录制诊断。
Q: 选择 DevTools 页面会改变我的脚本页面吗?
不,您的脚本必须选择其自身意图的页面。在比较证据之前,请确认两个工具正在检查同一文档。
不。回放重建已保存的页面更改。它既不会重新连接到实时浏览器,也不会重新运行原始应用程序脚本。
不。将警告视为诊断证据,并使用特定任务的接受标准。决定哪些异常和失败的请求对预期结果至关重要。
请先审核并编辑报告。日志、标题、页面内容和签名的URL即使在表单输入被遮蔽时,也可能暴露私人信息。
Nov. 17th 2026
从网页抓取、测试到 AI 驱动的自动化,一切都在云端运行。 探索 Cloud Browser →