Astron RPA 浏览器插件技术指南:深度搜索、shadowRoot 与跨域 iframe 定位及 crx/xpi 打包实战

原创2026-10-12 14:34:561,333 阅读
文章标签:工作流自动化低代码桌面应用AI Agent后端

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 极速浏览器等)。只需要两步:

  1. 在 src/3rd/rpa_websocket.js 的 custom_agent() 中为变体浏览器增加 modeAgent 映射条目,例如仓库现成的:
const modeAgent = {
  '360se': "$360se$",
  '360ChromeX': "$360ChromeX$",
  'chromium': "$chromium$"
}
return modeAgent[__BUILD_MODE__] || '';
  1. 在 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):

  1. 先用 document.elementsFromPoint(x, y) 一次性取回鼠标坐标 (x, y) 下所有层叠的元素(见 getElementsByPosition,L653-L663);
  2. 对每个元素取其 getBoundingClientRect(),过滤出 left <= x && top <= y && right >= x && bottom >= y(即矩形确实覆盖该点的元素);
  3. 计算每个元素 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:

  1. 用 selector.split('>$shadow$>') 把整条路径按 shadow 边界拆成若干层;
  2. 交给 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 不准确。

文档给出的解决方法是:

  1. 从插件主进程(background)获取 iframe 的嵌套关系:通过 parentFrameId 字段得到从顶层 frame 到目标 frame 的嵌套顺序(见 background/iframe.ts,getIframeElement 中循环 frames.find(frame => frame.frameId === targetFrame.parentFrameId) 逐级向上构建 framePath);
  2. 传入 x、y 坐标,按嵌套关系顺序逐层查找:background 侧 processFrames(L145-L167)对 framePath 中的每个 frame,在该 frame 上下文内执行 content 侧的 getIframeElement handler;
  3. 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):

  1. content 中标记当前窗口下所有 frame 元素:tagFrames() 遍历 getIFramesElements() 得到的全部 iframe/frame/object/embed(FRAME_ELEMENT_TAGS 定义在 common/constant.ts),对每个 frame 调用 postToIframe;
  2. 通过 iframe.contentWindow.postMessage 把 iframe 的 XPath 传给对应的 iframe:消息 key 为 setCurrentWindowIframeInfo,payload 包含 directoryXpath(frameDom) 生成的 iframeXpath、getIframeTransform 得到的 transform 缩放信息以及 getElementDirectory 得到的路径目录;
  3. 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 的绑定;
  4. 按 id 嵌套关系拼出完整 iframe 全路径:background 侧 findFrameByXpath 用 /$iframe$/ 作为分隔符拆分 iframeXpath,从根 frame(frameId === 0)开始逐段匹配 f.iframeXpath === seg && f.parentFrameId === current.frameId,最终定位到目标 frame;配合 buildFrameTree(L286-L317)还能输出整个 frame 树;
  5. 通过 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 条目。

方式二:不发布的手动打包

  1. 打开 Chrome 浏览器,进入 chrome://extensions/ 页面;
  2. 启用"开发者模式";
  3. 选择"打包扩展程序",浏览到扩展程序根目录(即 dist/ 构建产物目录);
  4. 第一次打包时私钥文件可以不填,打包完成后会在扩展程序根目录生成一个 .crx 文件和一个 .pem 密钥文件;
  5. .pem 文件在后续更新插件包时必须保留:使用同一个密钥文件打包会生成相同的插件 id,用于插件的覆盖更新(否则会导致插件 id 变化、已安装插件无法自动更新)。

Firefox:xpi 插件包

  1. Firefox 可以免费自行申请一个开发者账户;
  2. 上传自己打包的 xpi 文件后,可以不发布,直接下载该 xpi 文件即可安装到 Firefox;
  3. 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 与构建命令,最后按需走商店发布或白名单策略完成部署。

登录后查看全文
astron-rpa