Astron RPA 浏览器插件技术指南:深度搜索、shadowRoot 与跨域 iframe 定位及 crx/xpi 打包实战
Astron RPA 浏览器插件技术指南:深度搜索、shadowRoot 与跨域 iframe 定位及 crx/xpi 打包实战
本文以 astron-rpa 仓库中的 browser-plugin 说明文档 为主体,结合插件源码(element.ts、contentInject.ts、iframe.ts 等)深入讲解浏览器插件在网页自动化中的三大核心能力——深度搜索、shadowRoot 递归元素获取、跨域/同源 iframe 元素定位,并完整覆盖 Chrome/Edge/Firefox 及任意 Chromium 内核变体浏览器的构建打包与 crx/xpi 发布方案。读完本文,你将掌握该插件从"源码构建"到"元素定位原理"再到"浏览器商店发布"的完整链路,并能直接复用其定位策略解决自己的网页自动化难题。
插件定位与构建准备
Astron RPA 的浏览器插件是整套 RPA 体系中处理"网页相关自动化"的关键一环(对应英文 README 中 handles web-related automation 的描述)。它属于前端工程 frontend/packages/browser-plugin,当前版本为 5.2.12(见 package.json)。
插件由两类脚本构成:
- Background(后台脚本):入口 src/background.ts,负责 Tab 管理、iframe 嵌套关系获取、WebSocket 消息转发等主进程逻辑;
- Content(内容脚本):入口 src/content.ts,注入页面,负责元素定位、高亮、iframe 标记等。
构建环境要求 Node.js v20+,并使用 pnpm/Vite 工具链。插件对外提供能力的方式是:content 侧通过 window.handleSync/window.handle(见 contentInject.ts)暴露同步/异步处理入口,background 侧则通过 WebSocket 与 RPA 主程序通信——连接地址由环境变量 VITE_APP_WS_URL 指定,createWsApp 中会读取 UA 识别浏览器类型并 Base64 编码为 token 拼接在 WebSocket URL 上(见 src/3rd/rpa_websocket.js)。
构建与打包命令
通用打包:npm run build
执行 npm run build 即可打包出 Chrome/Edge 通用插件。其内部等价于依次执行:
cross-env BUILD_ENTRY=background vite build
cross-env BUILD_ENTRY=content vite build
即分别以 background 和 content 两个入口各构建一次,最终合并到 dist/ 目录。构建完成后,vite.config.ts 中的 extension-plugin 插件还会自动把 dist/ 压缩成 rpa-extension-v3-<版本号>-<构建模式>.zip 归档包,方便直接交给浏览器"加载已解压的扩展程序"。
按浏览器变体打包:npm run build:<browser>
package.json 中预置了两种变体命令:
npm run build:firefox # 构建 Firefox 专用插件(MV2)
npm run build:chromium # 构建 Chromium 专用插件
npm run build:all # 依次执行通用构建 + firefox + chromium
关键在于:<browser> 可以是任何 Chromium/Firefox 内核的变体浏览器(如 360 安全浏览器、360 极速浏览器等)。只需要两步:
- 在 src/3rd/rpa_websocket.js 的
custom_agent()中为变体浏览器增加modeAgent映射条目,例如仓库现成的:
const modeAgent = {
'360se': "$360se$",
'360ChromeX': "$360ChromeX$",
'chromium': "$chromium$"
}
return modeAgent[__BUILD_MODE__] || '';
- 在
package.json的scripts中新增对应构建命令,并把命令中的browser替换为目标浏览器的可执行文件名。Vite 会通过__BUILD_MODE__(在 vite.config.ts 中定义)把构建模式注入代码,custom_agent()据此返回对应的 agent 标识,WebSocket 握手时携带该 token,使 RPA 主程序能区分当前插件运行在哪个浏览器变体上。
Manifest 的差异化生成
manifest.ts 会在构建时根据构建模式自动生成 public/manifest.json:
- Chrome/Edge/Chromium 变体使用 Manifest V3:
background.service_worker方式、host_permissions: ['<all_urls>']、content_scripts 以all_frames: true注入http/https/file/ftp全部页面、run_at: document_start; - Firefox 模式自动降级为 Manifest V2:
background.scripts、移除了debugger权限、补充webRequest/webRequestBlocking、写入browser_specific_settings.gecko(strict_min_version: '58.0')。
构建所需的环境变量定义在 env.d.ts:VITE_APP_NAME、VITE_APP_WS_URL、VITE_APP_HOMEPAGE、VITE_FIREFOXID 等。
插件深度搜索功能
触发条件:鼠标悬浮 5 秒以上
深度搜索并非默认开启。在 contentInject.ts 的 moveListener 中,鼠标移动会启动两段定时器:
- 浅搜索:
ELEMENT_SEARCH_TRIGGER = 50(50ms,见 common/constant.ts)后立即用普通方式定位元素; - 深搜索:浅搜索完成后启动
DEEP_SEARCH_TRIGGER = 5 * 1000(5 秒)定时器,5 秒后把deepSearchEnabled置为true再执行一次findElement,随后立即复位。
也就是说,鼠标悬停超过 5 秒才会触发深度搜索。为什么需要它?深度搜索是为解决"部分元素被遮挡"的问题设计的:当一个元素被浮层、遮罩或其他元素盖住时,普通的 elementFromPoint 只能取到最上层元素,拿不到被遮挡的目标。但文档也明确提醒:对于未被遮挡的元素,深度搜索反而可能选中用户并不想要的那个元素,所以并非所有元素都需要触发深度搜索。
实现方式:elementsFromPoint + 距离最近匹配
核心实现在 element.ts 的 getClosestElementByPoint(约 L799-L815):
- 先用
document.elementsFromPoint(x, y)一次性取回鼠标坐标 (x, y) 下所有层叠的元素(见getElementsByPosition,L653-L663); - 对每个元素取其
getBoundingClientRect(),过滤出left <= x && top <= y && right >= x && bottom >= y(即矩形确实覆盖该点的元素); - 计算每个元素 left/top/right/bottom 到目标点 (x, y) 的距离(代码用
Math.hypot计算欧氏距离),取距离最近的一个;若存在多个结果,取第一项。
若浏览器不支持 elementsFromPoint,代码会回退到 getAllElementsPositionInBody()(L675-L704),遍历 document.body 下全部元素并过滤掉 <head>/<title>/<meta>/<script>/<style>/<link>、display:none、visibility:hidden 及宽高为 0 的元素后逐一计算位置。
shadowRoot 递归获取元素功能
递归穿透 shadow DOM
现代前端框架大量使用 Web Components / shadow DOM,普通选择器无法穿透 shadow root 边界。插件的 shadowRootElement 函数(element.ts)解决了这一问题:
export function shadowRootElement(point, shadowRoot, shadowPath = '', shadowDirs = []) {
const ele = shadowRoot.elementFromPoint(x, y) as HTMLElement
if (ele && ele.shadowRoot) {
// 追加 $shadow$ 层级,记录 nth-child 索引
shadowPath = shadowPath ? `${shadowPath}>$shadow$>${getNthCssSelector(ele)}${shadowNth}` : ...
return shadowRootElement(point, ele.shadowRoot, shadowPath, shadowDirs)
}
return { element: ele, path: shadowPath, dirs: shadowDirs }
}
它递归检查目标元素是否带 shadowRoot:若是,则继续在 shadowRoot.elementFromPoint 中向下查找,直到找到普通元素为止。递归过程中路径用 $shadow$ 作为分隔符拼接,例如:
html>body>div#app>my-widget>div:nth-child(2)>$shadow$>input:nth-child(1)
这样用户既能一眼识别这是穿过 shadow DOM 边界的路径,也便于插件后续按路径重新取回元素。
通过 path 取回元素:getElementBySelector
通过 path 获取元素时,插件同样能识别 $shadow$ 标记。element.ts 的 getElementBySelector 检测到选择器包含 $shadow$ 时,会走 getShadowElementsBySelector:
- 用
selector.split('>$shadow$>')把整条路径按 shadow 边界拆成若干层; - 交给
queryDeepShadow(L414-L442)逐层querySelectorAll:每层在document或上一层的el.shadowRoot内查询,命中后继续深入下一层 shadow root,直到取回最终目标元素。
与元素定位配套的还有 watcher.ts 中的 findNodeByCssSelectorStepwise:它会把包含 $shadow$ 的 CSS 选择器按 > 逐步拆分、逐段验证匹配,一旦某一步匹配失败就返回 notFoundIndex/notFoundStep,用于向用户报告"元素在第几层发生动态变化"。
重要限制
shadowRoot 元素暂时只支持 CSS 选择器获取,不支持 XPath 选择器获取。 这是因为 XPath 本身无法表达 shadow DOM 边界语义,插件因此采用 $shadow$ + CSS 的专用语法。相应地,在 formatElementInfo(contentInject.ts)中,shadow 元素的 checkType 被标记为 customization,且 cssSelector 会带上 $shadow$ 前缀路径。
frame 定位功能:跨域/同源 iframe 元素统一处理
iframe 定位是网页自动化中最棘手的场景之一。插件文档给出了完整的统一处理方案,核心结论是:跨域与同源 iframe 使用同一套方法——虽然同源限制更小,但按同一套方法处理可以避免冗余、减少变量、减少出错。
1. 跨域 iframe 的处理思路
跨域 iframe 定位难在三点:
- 同源策略(same-origin policy)限制下,父页面无法直接访问 iframe 内部 DOM;
- iframe 的
src可能固定,但 iframe 内 URL 会随页面跳转变动; - 同一个 Tab 下可能存在
src完全一致的多个 iframe,靠src匹配 iframe 不准确。
文档给出的解决方法是:
- 从插件主进程(background)获取 iframe 的嵌套关系:通过
parentFrameId字段得到从顶层 frame 到目标 frame 的嵌套顺序(见 background/iframe.ts,getIframeElement中循环frames.find(frame => frame.frameId === targetFrame.parentFrameId)逐级向上构建framePath); - 传入 x、y 坐标,按嵌套关系顺序逐层查找:background 侧
processFrames(L145-L167)对 framePath 中的每个 frame,在该 frame 上下文内执行 content 侧的getIframeElementhandler; - x、y 坐标逐层减去 iframe 的位置及盒模型:content 侧的
getIframeElement(contentInject.ts)拿到上一层的坐标后,用elementFromPoint找到 iframe 元素,再计算:
nextPos = {
x: (realX - left - borderLeft - paddingLeft) * dpr,
y: (realY - top - borderTop - paddingTop) * dpr,
}
即逐层减去 iframe 的 left/top 位置以及盒模型中的 borderLeft/borderTop 与 paddingLeft/paddingTop,换算成 iframe 内部 content 的准确坐标,并乘上 devicePixelRatio 处理高清屏缩放。同理,getFrameContentRect(element.ts)也同时扣除了 padding 与 border 得到 iframe 内容区矩形;getBoundingClientRect(L878-L896)还会考虑 window.currentFrameInfo.iframeTransform 中记录的 transform 缩放(scaleX/scaleY)。background 侧再把每层累计的 iframeContentRect 加到元素绝对坐标上(background/iframe.ts),从而得到目标元素在整个页面坐标系下的真实矩形。
详细实现分别见 getIframeElement 在 backgroundInject.ts(background 侧,调用 getIframeElement({ x, y }, activeElement))与 contentInject.ts(content 侧,执行逐层坐标换算)的处理。
2. 同源 iframe:同一套方法
同源 iframe 虽然可以直接访问 DOM,但插件刻意采用与跨域完全一致的处理流程,以消除两套逻辑带来的冗余变量与潜在出错点,保证定位结果的一致性。
3. iframe 元素定位:XPath 与 frameId 绑定
为了在多层嵌套中唯一定位 iframe,插件还维护了一套"iframe XPath ↔ iframe id"的绑定机制(content/iframe.ts):
- content 中标记当前窗口下所有 frame 元素:
tagFrames()遍历getIFramesElements()得到的全部 iframe/frame/object/embed(FRAME_ELEMENT_TAGS定义在 common/constant.ts),对每个 frame 调用postToIframe; - 通过
iframe.contentWindow.postMessage把 iframe 的 XPath 传给对应的 iframe:消息 key 为setCurrentWindowIframeInfo,payload 包含directoryXpath(frameDom)生成的 iframeXpath、getIframeTransform得到的 transform 缩放信息以及getElementDirectory得到的路径目录; - iframe 内通过
window.addEventListener('message', ...)接收 XPath 并传给主进程:子 iframe 收到消息后写入自己的currentFrameInfo,并调用requestFrameId()从 background 申请自己的frameId,随后用postMessage(key 为bindCurrentWindowIframeInfo)把frameId回传给父窗口,父窗口的tagFrameId把frameId写入 iframe 元素的data-astron-frame-id属性(content/iframe.ts)——这就完成了 iframe 的 XPath 路径与 id 的绑定; - 按 id 嵌套关系拼出完整 iframe 全路径:background 侧 findFrameByXpath 用
/$iframe$/作为分隔符拆分 iframeXpath,从根 frame(frameId === 0)开始逐段匹配f.iframeXpath === seg && f.parentFrameId === current.frameId,最终定位到目标 frame;配合buildFrameTree(L286-L317)还能输出整个 frame 树; - 通过
iframeXpath字段定位目标 iframe 及其中的目标元素:定位结果会写入元素信息对象的iframeXpath/iframePathDirs字段,后续任何元素操作(handleInContent、getOuterHTML等)都通过findTabAndFrame携带该字段精确路由到对应 frame(backgroundInject.ts)。
content 侧还提供了三个配套的 frame handler(contentInject.ts):getFramePosition(按 iframeXpath 或 URL 匹配返回 frame 内容矩形,URL 匹配使用 UrlMatcher 的 DOMAIN 级别判定)、findIframeId(按 XPath 读取 data-astron-frame-id)、elementLocatorFrameId(广播到所有 frame,反向探测哪个 frame 中存在目标元素并返回其 frameId)。
4. 注意事项
iframeXpath 与其他元素的定位逻辑完全相同,统一查找逻辑,同样存在动态性问题——即页面 DOM 变化(iframe 增删、src 变化、元素结构变动)后,已保存的 iframeXpath/元素路径可能失效。仓库为此提供了 elementChangeWatcher(watcher.ts)逐级定位失败节点,并在 tests/iframe-diagnostic-tool.html 中提供了一个"Iframe MouseMove 事件穿透诊断工具"页面,用于排查 iframe 上鼠标事件穿透与坐标换算问题。
构建 crx / xpi 包说明
Chrome:crx 插件包
方式一:发布到 Chrome 插件商店(推荐)
推荐使用 Chrome Developer Dashboard 发布到 Chrome 插件商店。注意 Chrome 开发者账户需要付费。若不发布到插件商店,Chrome 会限制启用该插件,需要把插件加入白名单:
- Windows:以注册表方式写入
Software\Policies\Google\Chrome\ExtensionInstallAllowlist; - Linux:写入
/etc/opt/chrome/policies/managed/policy.json。
策略详情可查阅 Chrome 企业版策略文档中的 ExtensionInstallAllowlist 条目。
方式二:不发布的手动打包
- 打开 Chrome 浏览器,进入
chrome://extensions/页面; - 启用"开发者模式";
- 选择"打包扩展程序",浏览到扩展程序根目录(即
dist/构建产物目录); - 第一次打包时私钥文件可以不填,打包完成后会在扩展程序根目录生成一个
.crx文件和一个.pem密钥文件; .pem文件在后续更新插件包时必须保留:使用同一个密钥文件打包会生成相同的插件 id,用于插件的覆盖更新(否则会导致插件 id 变化、已安装插件无法自动更新)。
Firefox:xpi 插件包
- Firefox 可以免费自行申请一个开发者账户;
- 上传自己打包的 xpi 文件后,可以不发布,直接下载该 xpi 文件即可安装到 Firefox;
- Firefox 插件需要自行打包,使用自己的开发者账户上传,构建自己的 xpi 文件。构建时使用
npm run build:firefox,产物为 MV2 格式的 Firefox 专用插件,且 manifest 中已写入browser_specific_settings.gecko.id(VITE_FIREFOXID环境变量),满足 Firefox 的签名/安装要求。
质量保障与测试
插件工程内置了完整的测试体系(基于 Vitest):
npm run test:运行 Node 环境的单元测试(vitest,见 vite.config.ts),测试用例位于 src/test,覆盖 background 与 content 两大模块,例如 content.element.test.js 验证了 iframe 场景下getText/getAttr/坐标换算等元素工具函数;npm run test:browser/npm run coverage:使用vitest.browser.config.js在真实浏览器环境中运行并输出覆盖率;npm run tsc:TypeScript 类型检查;npm run lint:fix:ESLint 自动修复。
小结
围绕 browser-plugin README 的说明,可以梳理出插件定位体系的完整脉络:
- 深度搜索解决"元素被遮挡"问题:5 秒悬停触发,
elementsFromPoint取全量元素后按到鼠标点的距离取最近者; - shadowRoot 递归解决"shadow DOM 边界穿透"问题:
$shadow$路径语法 + 逐层querySelectorAll,目前仅支持 CSS 选择器; - iframe 统一处理解决"跨域/同源/同 src 重复 iframe"问题:
parentFrameId嵌套顺序 + 逐层坐标扣除盒模型 + postMessage 绑定 iframeXpath 与 frameId; - crx/xpi 打包覆盖 Chrome/Edge/Firefox 及任意 Chromium 内核变体(通过
custom_agent与构建模式注入识别)。
对于要接入 Astron RPA 网页自动化能力的开发者,建议先运行 npm run build 构建通用插件并以"加载已解压的扩展程序"方式验证元素拾取,再针对目标浏览器变体配置 custom_agent 与构建命令,最后按需走商店发布或白名单策略完成部署。