企业官网建设流程全解析

Archon 浏览器自动化指南：用 playwright-cli run-code 执行任意 Playwright 代码

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

本指南讲解 Archon 仓库内置的playwright-cli技能中run-code命令的完整用法。当 CLI 内置命令（click、fill、goto等）无法覆盖你的高级浏览器自动化场景时，run-code允许你直接执行任意 Playwright 代码，用于地理位置模拟、权限授予、媒体仿真、跨页面数据抓取等复杂任务。读完本文，你将掌握run-code的语法约束、常用 API 组合以及从登录到数据采集的完整实战方案。

run-code 是什么：CLI 内置命令之外的逃生舱

playwright-cli是 Archon 仓库中随.claude/skills/分发的浏览器自动化技能（定义见 SKILL.md），它把常见操作封装成了open、goto、click、fill、snapshot等命令，并支持--raw输出与管道组合。但真实网页场景无穷无尽——动态渲染、权限弹窗、文件下载、iframe 嵌套、剪贴板读写……这些需求无法靠固定命令穷举。

run-code就是为此设计的通用通道：它把一段 Playwright 代码字符串交给 CLI 执行，让你在保持 CLI 会话上下文（同一个浏览器实例、同一个 Page 对象）的前提下，自由调用 Playwright 的全部 API。这与本技能其他参考文档（如 storage-state.md 中"高级：多条 Cookie 操作请用 run-code"、request-mocking.md 中的网络拦截）形成互补——凡是 CLI 没有直接命令的复杂操作，都收敛到run-code。

语法与执行约束

基础语法

run-code接受一段以page为参数的 async 箭头函数，CLI 会在内部将其包裹在(...)中求值并调用：

playwright-cli run-code "async page => { // 你的 Playwright 代码 // 通过 page.context() 访问浏览器上下文操作 }"

从文件加载

代码较长时可写入文件，用--filename参数加载：

playwright-cli run-code --filename=./my-script.js

关键约束

• 代码必须是一个单一函数表达式（single function expression），不能是语句序列；
• 会被包裹在(...)中求值，因此不支持import/export/require语法——依赖的 API 全部来自 Playwright 全局可用对象（page、page.context()等）；
• 函数默认接收page参数，所有浏览器上下文操作通过page.context()获取 BrowserContext 实例。

提示：在 CLI 参数中传入多行代码时，注意 shell 的引号转义；在 Windows 的cmd.exe/PowerShell 中如代码含&等特殊字符，需按 SKILL.md 的说明转义。

地理位置模拟（Geolocation）

需要测试定位类应用（地图、门店搜索、地区化内容）时，先用grantPermissions授予geolocation权限，再调用setGeolocation设置经纬度：

# 授予地理位置权限并设置位置（旧金山） playwright-cli run-code "async page => { await page.context().grantPermissions(['geolocation']); await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 }); }" # 设置为伦敦 playwright-cli run-code "async page => { await page.context().grantPermissions(['geolocation']); await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 }); }" # 清除地理位置覆盖 playwright-cli run-code "async page => { await page.context().clearPermissions(); }"

注意clearPermissions()会清空全部已授予的权限，如果只需要移除地理位置覆盖而保留其他权限，可重新只授予所需权限集合。该能力在 SKILL.md 的 DevTools 一节中也有对应示例（grantPermissions(['geolocation'])），是位置敏感型功能回归测试的标准做法。

浏览器权限授予（Permissions）

批量授予多个权限

playwright-cli run-code "async page => { await page.context().grantPermissions([ 'geolocation', 'notifications', 'camera', 'microphone' ]); }"

针对特定源（Origin）授予权限

权限通常按 origin 隔离，测试第三方嵌入内容时可限定范围：

playwright-cli run-code "async page => { await page.context().grantPermissions(['clipboard-read'], { origin: 'https://example.com' }); }"

授予后会弹出系统权限提示的网站（通知、摄像头、麦克风、地理位置、剪贴板等）都可以用这一模式静默授权，避免自动化流程被原生弹窗卡死。

媒体仿真（Media Emulation）

无需真机即可验证深色模式、减少动效、打印样式等响应式表现：

# 模拟深色配色 playwright-cli run-code "async page => { await page.emulateMedia({ colorScheme: 'dark' }); }" # 模拟浅色配色 playwright-cli run-code "async page => { await page.emulateMedia({ colorScheme: 'light' }); }" # 模拟减少动效（reduced motion，无障碍测试常用） playwright-cli run-code "async page => { await page.emulateMedia({ reducedMotion: 'reduce' }); }" # 模拟打印媒体类型 playwright-cli run-code "async page => { await page.emulateMedia({ media: 'print' }); }"

emulateMedia的media选项支持'screen'/'print'，结合playwright-cli pdf --filename=page.pdf（见 SKILL.md 的 Save as 一节）可以完整走通"打印样式验证 → PDF 导出"的链路。

等待策略（Wait Strategies）

SPA 页面渲染时机多变，正确等待是稳定性的关键：

# 等待网络空闲 playwright-cli run-code "async page => { await page.waitForLoadState('networkidle'); }" # 等待某个元素消失（如 loading 指示器） playwright-cli run-code "async page => { await page.locator('.loading').waitFor({ state: 'hidden' }); }" # 等待函数返回 true（如应用状态就绪标记） playwright-cli run-code "async page => { await page.waitForFunction(() => window.appReady === true); }" # 带超时等待（默认 30 秒，这里显式给 10 秒） playwright-cli run-code "async page => { await page.locator('.result').waitFor({ timeout: 10000 }); }"

实战建议：优先用waitForFunction等待业务就绪标志（如window.appReady）而非固定setTimeout；元素等待时显式设置timeout可以避免慢速环境下的误报超时。

Frames 与 Iframes

嵌套页面（广告位、第三方支付、OAuth 弹窗 iframe）需要切换 frame 上下文：

# 进入 iframe 内部操作 playwright-cli run-code "async page => { const frame = page.locator('iframe#my-iframe').contentFrame(); await frame.locator('button').click(); }" # 列出页面所有 frame 的 URL playwright-cli run-code "async page => { const frames = page.frames(); return frames.map(f => f.url()); }"

第二个示例很适合自动化排查"页面里有几个 iframe、各来自哪个域名"，返回值可以直接被 CLI 展示，配合--raw还能喂给其他工具做断言。

文件下载处理

下载类功能（导出报表、下载合同）用事件驱动的方式处理：

playwright-cli run-code "async page => { const downloadPromise = page.waitForEvent('download'); await page.getByRole('link', { name: 'Download' }).click(); const download = await downloadPromise; await download.saveAs('./downloaded-file.pdf'); return download.suggestedFilename(); }"

要点：必须先注册waitForEvent('download')再触发点击，避免竞态；saveAs把文件保存到本地工作目录；suggestedFilename()返回服务器建议的文件名，适合作为返回值做后续校验。

剪贴板读写

# 读取剪贴板（需要 clipboard-read 权限） playwright-cli run-code "async page => { await page.context().grantPermissions(['clipboard-read']); return await page.evaluate(() => navigator.clipboard.readText()); }" # 写入剪贴板 playwright-cli run-code "async page => { await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!'); }"

剪贴板权限同样属于 浏览器权限授予 一节所说的 origin 限定权限，若页面运行在https上下文之外，navigator.clipboard可能不可用，需结合实际情况评估。

页面信息获取

快速获取当前页面状态，用于断言或日志：

# 获取页面标题 playwright-cli run-code "async page => { return await page.title(); }" # 获取当前 URL playwright-cli run-code "async page => { return page.url(); }" # 获取页面完整 HTML playwright-cli run-code "async page => { return await page.content(); }" # 获取视口尺寸 playwright-cli run-code "async page => { return page.viewportSize(); }"

这几个示例返回值简洁，特别适合配合 SKILL.md 中的--raw选项使用，例如playwright-cli --raw run-code "async page => page.url()"把 URL 直接喂给管道中的下一个命令。

在页面中执行 JavaScript（page.evaluate）

evaluate是run-code里最常用的 API，可以在页面上下文中运行任意脚本并取回结果：

# 执行 JS 并返回对象 playwright-cli run-code "async page => { return await page.evaluate(() => { return { userAgent: navigator.userAgent, language: navigator.language, cookiesEnabled: navigator.cookieEnabled }; }); }" # 向 evaluate 传参（第二参数会作为函数入参传入） playwright-cli run-code "async page => { const multiplier = 5; return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier); }"

注意evaluate的序列化边界：传参和返回值都必须是可序列化的值（JSON 兼容类型），不能传递 DOM 元素或函数引用。run-code所在 CLI 作用域的变量（如multiplier）可以自由引用，但会作为参数显式传入页面上下文。

错误处理：try-catch 容错

页面元素可能因条件渲染而不存在，用 try-catch 把失败变成可控结果：

playwright-cli run-code "async page => { try { await page.getByRole('button', { name: 'Submit' }).click({ timeout: 1000 }); return 'clicked'; } catch (e) { return 'element not found'; } }"

这种"探测式"写法非常适合做分支逻辑：按钮存在则点击、不存在则返回标记，调用方再根据返回值决定后续流程。超时时间{ timeout: 1000 }让探测快速失败而不是等待默认 30 秒。

复杂工作流实战

登录并保存会话状态

登录后把 storage state 存成文件，后续会话直接复用（与 storage-state.md 的state-save/state-load配合）：

playwright-cli run-code "async page => { await page.goto('https://example.com/login'); await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com'); await page.getByRole('textbox', { name: 'Password' }).fill('secret'); await page.getByRole('button', { name: 'Sign in' }).click(); await page.waitForURL('**/dashboard'); await page.context().storageState({ path: 'auth.json' }); return 'Login successful'; }"

要点：waitForURL('**/dashboard')用 glob 匹配跳转后的 URL，避免等待固定地址造成偶发失败；storageState写入的auth.json可供playwright-cli state-load auth.json在后续新会话中恢复，实现"一次登录、处处复用"。请遵循 storage-state.md 的安全建议：包含认证令牌的状态文件不要提交进版本库，建议加入.gitignore并在自动化结束后删除。

跨多页抓取数据

playwright-cli run-code "async page => { const results = []; for (let i = 1; i <= 3; i++) { await page.goto(\`https://example.com/page/\${i}\`); const items = await page.locator('.item').allTextContents(); results.push(...items); } return results; }"

模板字符串（模板字面量）中的${i}在 shell 双引号内可能被 shell 展开，CLI 使用反引号包裹以保证安全。返回的results数组可直接被 CLI 展示；对大规模抓取，建议每次goto之间结合上文等待策略中的waitForLoadState('networkidle')确保渲染完成。

小结：run-code 在 Archon 技能体系中的定位

在 Archon 的浏览器自动化技能体系（.claude/skills/playwright-cli/SKILL.md）中，run-code是"最后手段也是最强手段"：固定命令负责高频操作与可读性，run-code负责无限扩展。它与本技能其余参考文档——playwright-tests.md（测试运行调试）、request-mocking.md（网络拦截）、storage-state.md（存储状态）、tracing.md（追踪）——共同覆盖了现代 Web 自动化从权限、定位、等待、媒体到下载、存储、网络的完整场景。掌握本文的代码模式后，你可以把任意 Playwright 脚本迁移为run-code命令，让浏览器自动化真正"指哪打哪"。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon