L6-37：浏览器自动化 —— 让AI自己打开网页帮你干活

🎯 学 gstack 的 Playwright 驱动的无头浏览器：不是普通的 curl 或 HTTP 客户端，而是完整的 Chromium 实例——可以导航页面、执行 JavaScript、截取全页截图、监控控制台错误和性能指标——让自动化能"看到"用户看到的东西。 ⏱️ 预计时间：30 分钟

💡 新手提示：浏览器自动化和普通 HTTP 请求的区别——HTTP 请求只能拿到 HTML 代码，浏览器自动化能执行 JavaScript、看到渲染后的页面，就像真人打开了网页一样。对于现代 SPA 应用（React/Vue），这是唯一的验证方式。

---

[!quote]- 📖 原Skill精要 技能名称：browse 核心功能：快速无头浏览器（Playwright）用于 QA 测试和网站自用。导航任意 URL、交互元素、验证页面状态、前后操作对比、标注截图、检查响应式布局、测试表单上传、处理对话框、断言元素状态。约 100ms/命令。将被 [[L6-20-自动化测试修复|qa]]、[[L6-27-金丝雀监控|canary]]、[[L6-23-性能基准测试|benchmark]]、[[L6-13-开发者体验审计|devex-review]] 等多个 Skill 调用。 所属体系：gstack 虚拟工程团队 协作关系：gstack 浏览器自动化的核心基础设施，几乎所有需要 Web 交互的 Skill 都依赖它

§1 课程概览

browse 是 gstack 的 Playwright 驱动无头浏览器——不是 curl/http.get，而是一个完整的 Chromium 实例。核心能力链：goto（导航 + 等待 JS 渲染）→ console --errors（捕获 JS 运行时错误）→ perf（测量 Web Vitals 性能指标）→ text（提取渲染后可见文本）→ snapshot（全页截图 + 注释标注）→ network --errors（HTTP 4xx/5xx 检测）。约 100ms/命令。被 qa、canary、benchmark、devex-review、design-review 等多个 Skill 作为基础设施调用。本课通过电商首页全流程验证案例，展示从桌面端到移动端的完整浏览器自动化脚本。

[!tip] 白话小课堂 浏览器自动化不是 curl——它真的打开一个 Chromium 浏览器来干活：执行 JavaScript、渲染 CSS、截图、测量 Web Vitals 性能指标。对 React/Vue 这些 SPA 应用来说，curl 只能拿到一个空壳 <div id='root'></div>，浏览器自动化才能看到用户真正看到的东西。部署后用 $B 走一遍关键页面，只需要几行命令：控制台有 JS 报错吗？LCP 超 2.5 秒了吗？移动端布局崩了吗？首页的"双11大促" banner 还在吗？**用 curl 验证你只能确认"服务器没挂"，用浏览器自动化你才能确认"页面没坏"。**这节课学完你会拿到一套完整的浏览器验证脚本模板，可以放进 CI/CD 流水线里自动跑。

§2 Browse 的能力——不只 HTTP，是完整的浏览器

Browse vs curl/http.get 的核心区别

核心命令链

$B goto <url>           —— 导航到 URL + 等待 JS 渲染完成
$B console --errors     —— 获取控制台错误（Error/Uncaught/TypeError）
$B perf                 —— 性能指标（TTFB/FCP/LCP/DOM Content Loaded）
$B text                 —— 提取渲染后的可见文本
$B snapshot -i -a       —— 带注释的截图（交互元素 + 无障碍标注）
$B network --errors     —— 网络请求错误（HTTP 4xx/5xx）
$B cookie --set ...     —— 设置 Cookie（配合 setup-browser-cookies）

为什么 SPA 应用必须用浏览器自动化？

三个技术维度：

1. JavaScript 执行：SPA 的 HTML 是空壳 <div id="root"></div>，所有内容由 JS bundle 动态渲染。curl 只拿到空壳——看不到任何实际内容
2. 渲染后 DOM：很多 SPA 的内容是异步加载的（API 调用返回数据后渲染），浏览器可以等待网络请求完成、DOM 更新后再验证
3. 路由验证：SPA 使用客户端路由（如 /products/123），curl 可能返回 404 或首页 HTML——只有浏览器能模拟真实的客户端路由跳转

§3 Snapshot（截图）——一图胜千言

基本截图能力

• $B snapshot -o "output.png" —— 保存到文件
• $B snapshot -i —— 内联注释（标注关键元素：可交互元素、布局问题、性能问题、可访问性问题）
• $B snapshot -a —— 可访问性标注（缺失 alt、低对比度等 WCAG 违规）
• $B snapshot -f —— 全页截图（不只是当前视口，包括折叠以下的内容）

注释模式标记的四类问题

• 可交互元素：按钮、链接、输入框——标注出所有可操作的元素
• 布局问题：重叠、溢出——视觉上的结构问题
• 性能问题：大图片（>1MB）、未优化的字体——影响加载速度的元素
• 可访问性问题：缺失 alt、低对比度——WCAG 违规

在不同 gstack 工作流中的使用

• /canary：$B snapshot → 部署后验证截图，与部署前基线对比
• /land-and-deploy：$B snapshot → 部署报告中附上页面截图
• /design-review：$B snapshot → 设计审查对比（与设计稿对比差异）
• /qa：$B snapshot → 视觉回归测试（自动化对比前后版本差异）

§4 Console 监控——JS 错误无处隐藏

Console 命令

$B console --errors 捕获：Error, Uncaught, TypeError, ReferenceError, Failed to load。过滤掉 warnings, info, debug（减少噪音）。输出每条错误的时间戳 + 来源文件 + 错误消息。

部署后的验证逻辑

部署后 $B console --errors：

• 0 errors → PASS（部署没有引入新的 JS 错误）
• 1+ errors → WARNING → 截图审查 → 决定是否回退

HTTP 200 OK 不足以验证前端健康

一个典型的静默故障场景：API 返回 200 OK + 正确 JSON → 前端 JS 解析 JSON → data.items.map() 而 data.items 在新 API 版本中变成了 data.products → TypeError: Cannot read property 'map' of undefined → 整个页面渲染中断 → 用户看到空白页。

• HTTP 验证：200 OK ✓（误以为一切正常）
• console --errors：TypeError: Cannot read property 'map' of undefined at main.js:234 → WARNING（发现了真正的故障）

HTTP 200 只确认"服务器没挂"，console --errors 确认"页面没坏"。

§5 Perf——性能就是用户体验

核心性能指标

• TTFB (Time to First Byte)：服务器响应有多快？（后端性能）
• FCP (First Contentful Paint)：用户多久看到第一个内容？（首屏感知）
• LCP (Largest Contentful Paint)：主要内容（Hero 图/主标题）多久渲染完成？（用户觉得"加载完了"的时刻）
• DOM Content Loaded：DOM 构建完成
• DOM Interactive：页面可交互
• Total Load：完全加载（包括异步资源）

LCP 为什么比 Total Load 更能反映"用户觉得加载完了"？

LCP 测量视口中最大可见元素（通常是 Hero 图或主标题）完全渲染的时间——用户看到主要内容 = "加载完了"。Total Load 可能包含用户看不到的异步资源（tracking scripts、延迟加载的图片等）——对用户来说这些不重要。

在 canary 和 benchmark 中的应用

• canary：部署后 perf → 与部署前对比 → 加载时间增长 > 50% → DEGRADATION → 加载时间增长 > 100% → REGRESSION
• benchmark：多次采集取中位数（平抑网络波动）→ 与 baseline 对比 → 检测性能回归

§6 结构拆解

§7 电商 Skill 案例：商品详情页多端自动化验证（桌面+移动）

🛒 实战案例：某电商平台的商品详情页是转化漏斗的核心页面（日均PV 80万，加购率决定GMV）。每次部署后需要验证：页面是否正常渲染、控制台有无JS错误、性能指标是否达标（LCP<2.5s）、关键元素（价格/变体选择/加购按钮）是否存在——桌面端和移动端都要验证。使用$B（Playwright驱动的browse命令）建立部署后多端自动化验证流水线。

• 桌面端验证（1920x1080视口）：6步检查流水线——(1)$B goto https://mega-shop.com/products/12345→页面200 OK加载1.2s；(2)$B console --errors→0 errors clean；(3)$B perf→关键性能指标：LCP 980ms(<2.5s预算✓)、FCP 450ms、CLS 0.01；(4)$B text→grep验证关键元素存在——商品标题✓、价格¥299✓、变体选择器"颜色: 黑色/白色"✓、"加入购物车"按钮✓、库存状态"有货"✓；(5)$B snapshot→截图保存deploy-verify/product-desktop.png用于人工对比基线；(6)交互测试——点击"白色"变体→商品图片联动切换✓、hover商品大图→zoom效果触发✓。
• 移动端验证（375x812 iPhone视口）：3项移动端专项检查——(1)$B goto https://mega-shop.com/products/12345 --viewport "375x812"→页面200 OK；(2)$B text→grep"加入购物车"✓（关键——移动端加购按钮固定底部sticky，桌面端在信息区右侧。验证移动端布局未崩坏，按钮可见且可点）；(3)$B snapshot→截图保存与移动端基线对比，检测响应式布局崩坏（如桌面端3列商品网格→移动端375px被挤压到不可读、水平滚动条出现）。
• 移动端特有问题的1次发现：某次部署后桌面端验证全部通过，但移动端$B text未找到"加入购物车"→截图发现按钮被底部导航栏遮挡（z-index冲突）。根因：新版本底部导航的CSS z-index: 999覆盖了加购按钮的z-index: 100。**如果只验证桌面端——这个bug会逃逸到生产环境，移动端用户（占总流量62%）无法加购。**修复后重新验证通过。
• CI/CD集成：将browse验证脚本集成到.github/workflows/deploy.yml→部署到staging后自动运行→有任何一步失败阻断推进到生产。性能降级策略——LCP>4s→WARN（不阻断但发告警）、console errors>0→FAIL阻断、关键元素缺失→FAIL阻断。验证耗时：桌面端5.2s+移动端4.8s=总计10s（轻量级，不拖慢部署流水线）。

🔑 启示：browser自动化验证的"移动端专项检查"不是nice-to-have——它是must-have。只验证桌面端会漏掉的移动端问题：响应式布局崩坏（375px视口下的卡片挤压）、触摸交互缺失（桌面端hover显示的按钮在移动端永远找不到）、资源加载性能（1920px Hero大图2MB在3G网络下8s——桌面端WiFi感受不到）。多端验证的ROI在第一次发现移动端专有bug时就回本了。

[!info] 参考来源 Browse 的 Playwright 驱动参考了 Playwright 官方文档。性能指标参考 Web Vitals 标准。自动化验证模式参考了 Checkly 的浏览器监控最佳实践。

§8 掌握检验

Q1：Browse（Playwright Chromium）相比 curl/http.get 的核心优势是什么？

• A) Browse 速度更快，延迟更低
• B) Browse 能完整渲染页面（HTML + CSS + JS），捕获控制台错误，测量真实的浏览器性能指标——对 SPA 应用这是唯一的验证方式
• C) Browse 不需要安装任何依赖
• D) Browse 可以直接修改服务器端代码

Q2：Perf 命令中，LCP（Largest Contentful Paint）为什么比 Total Load 更能反映"用户觉得加载完了"？

• A) LCP 总是比 Total Load 数值大
• B) LCP 测量的是视口中最大内容元素（Hero 图、主标题）完全渲染的时间——用户看到主要内容 = 页面"加载完了"，而 Total Load 可能包含用户看不到的异步资源
• C) Total Load 不准确，不被建议使用
• D) LCP 是 Google 发明的，所以更好

Q3：$B snapshot -i（注释模式）标记哪些类型的问题？这些标注在 design-review 和 canary 中分别解决什么不同问题？请从"设计审查者需要的视觉信息"和"部署验证者需要的异常信息"两个角度对比。

Q4：为什么 SPA 应用（React/Vue/Angular）必须用浏览器自动化验证，而不能用 curl 或 HTTP 客户端？请从"JavaScript 执行"、"渲染后 DOM"、和"路由验证"三个技术维度解释。

Q5：部署后用 $B console --errors 检查 JS 错误，与只看 HTTP 状态码（200 OK）相比，发现了什么额外的问题类？给出一个具体场景：一个 API 端点返回 200 OK + 正确 JSON 数据，但前端因为有 JS 错误而显示空白页面——HTTP 状态码验证会认为一切正常，console --errors 会发现什么？

Q6：电商首页验证中为什么需要同时验证桌面端（1920x1080）和移动端（375x812）？如果只验证桌面端，可能漏掉哪些移动端特有的问题？请给出至少两个"桌面端完全正常但移动端出了问题"的具体场景（涉及响应式布局、触摸交互、或资源加载策略）。

§9 答案

点击查看答案

Q1：B —— Browse 的核心优势是完整的浏览器能力：渲染页面（执行 JS）、捕获控制台错误（Error/Uncaught/TypeError）、测量真实性能指标（FCP/LCP/TTFB）、全页截图、提取渲染后的可见文本。

Q2：B —— LCP 测量视口中最大可见元素完全渲染的时间——通常是 Hero 图或主标题。用户看到主要内容 = 页面"加载完了"。Total Load 可能包含用户看不到的异步资源。

Q3：注释模式标记四类问题：可交互元素、布局问题（重叠/溢出）、性能问题（大图片/未优化字体）、可访问性问题（缺失 alt/低对比度）。design-review：标注与设计规范不符（间距不一致、颜色偏离）。canary：标注与部署前基线的差异（缺失元素、布局崩溃）。design-review 关注"是否合设计意图"，canary 关注"是否与之前一致"。

Q4：①JS 执行：SPA 的 HTML 是空壳 <div id="root">，curl 看不到内容。②渲染后 DOM：异步加载的内容（API 返回数据后渲染），浏览器可等待 DOM 更新。③路由验证：SPA 客户端路由 /products/123，curl 可能返回 404——只有浏览器能模拟客户端路由跳转。

Q5：HTTP 200 只确认服务器返回了内容，不确认浏览器渲染成功。场景：API 返回 200 + 正确 JSON → JS 解析时 data.items.map() 而 data.items 变成了 data.products → TypeError → 空白页。HTTP 验证：200 OK ✓（误以为正常）。console --errors：TypeError at main.js:234 → WARNING（发现真正故障）。

Q6：①响应式布局：桌面端 3 列网格（350px/卡片），移动端 375px → 卡片 < 125px 不可读。②触摸交互：桌面端 hover 显示"加入购物车"，移动端无 hover → 按钮永远找不到。③资源加载：移动端加载 1920px 大图（2MB），3G 网络 8s——桌面端 WiFi 感受不到。

（5/6 通过）

---

延伸阅读

• [[L6-36-项目复盘大师|上一课：项目复盘大师]]
• [[L6-38-AI浏览器控制台|下一课：AI浏览器控制台]] —— 专用浏览器（携带登录状态）
• [[L6-27-金丝雀监控|相关：Canary 监控——browse 的主要消费方]]
• [[L6-20-自动化测试修复|相关：QA 自动化测试——browse 的核心调用方]]