1. 项目概述UI Recorder是什么以及它为何值得深究如果你是一名前端开发者、测试工程师或者对自动化测试感兴趣那么“UI Recorder”这个名字你大概率不会陌生。简单来说它是一个用于录制用户在浏览器中的操作并自动生成可执行测试脚本的工具。听起来是不是有点像“录屏回放”没错核心逻辑确实如此但它的价值远不止于此。在敏捷开发和持续集成的今天UI自动化测试是保证产品质量、提升回归效率的关键环节。然而编写和维护UI测试脚本一直是个痛点——代码量大、维护成本高、对测试人员编程能力要求不低。UI Recorder的出现旨在通过“所见即所得”的录制方式极大地降低自动化测试的入门门槛和维护成本。但今天我们不打算只停留在“如何使用”的层面。市面上关于UI Recorder的教程已经很多了。我们真正要深挖的是它的架构。具体来说是标题点明的“Chrome扩展与Node.js的协同工作”。为什么一个录制工具需要这两种看似不相关的技术组合Chrome扩展负责什么Node.js又扮演什么角色它们之间如何通信、如何分工协作才能实现从录制到生成脚本再到执行的一整套流程理解这套架构不仅能让你在使用UI Recorder时更加得心应手排查问题更快更准更能为你自己设计类似的、需要连接浏览器前端与本地后端服务的工具时提供一套清晰、可复用的技术蓝图。这就像不仅会开车还懂发动机原理和传动系统面对故障时你就不再束手无策。2. 核心架构拆解为什么是Chrome扩展 Node.js要理解UI Recorder的架构首先要明白它要解决的核心问题如何无侵入、高保真地捕获用户在浏览器中的交互并将这些交互转化为结构化的、可编程的事件数据最终在本地生成并运行测试脚本。这个目标拆解开来就自然引出了两个主战场浏览器环境这是用户交互发生的地方。我们需要在这里监听所有用户操作——点击、输入、滚动、跳转等并获取操作目标的详细信息如DOM元素的唯一选择器、属性、坐标等。这个过程必须足够轻量、实时且不能干扰用户正常浏览。本地开发/测试环境这是处理数据、生成脚本、管理测试套件、连接其他服务如测试报告、CI/CD的地方。这里需要文件IO、进程管理、网络服务、依赖包管理等能力。现在我们来看技术选型如何匹配这两个战场。2.1 Chrome扩展的角色浏览器内的“侦察兵”与“信号兵”Chrome扩展是解决“浏览器环境”问题的绝佳选择。它由几个关键部分组成在UI Recorder中各自承担重任Content Script内容脚本这是注入到每个被录制页面的JavaScript代码。它像潜伏在页面里的“侦察兵”直接与页面DOM交互。它的核心职责是事件监听通过addEventListener监听页面的click,input,change,submit,keydown等所有用户交互事件。DOM信息提取当事件发生时内容脚本需要立刻捕获事件目标元素并计算出一个或多个能唯一、稳定定位到该元素的CSS选择器或XPath。这是录制准确性的基石。一个健壮的算法会考虑id、class、>{ “name”: “com.mycompany.uirecorder”, “description”: “UI Recorder Host”, “path”: “/usr/local/bin/uirecorder-host.js”, “type”: “stdio”, “allowed_origins”: [“chrome-extension://你的扩展ID/”] }连接建立当Chrome扩展调用chrome.runtime.connectNative(“com.mycompany.uirecorder”)时Chrome浏览器会根据名称找到配置文件并启动path指定的Node.js程序。消息格式通信双方通过stdin和stdout传递JSON消息。每条消息前4个字节是消息体的长度小端序后面紧跟JSON字符串。Node.js端需要不断读取process.stdin来获取数据并向process.stdout写入数据来响应。// Node.js宿主示例代码片段 const fs require(‘fs’); process.stdin.on(‘readable’, () { let lengthBytes process.stdin.read(4); if (!lengthBytes) return; let length lengthBytes.readUInt32LE(0); let message JSON.parse(process.stdin.read(length)); // 处理来自扩展的消息 handleMessage(message); }); function sendToExtension(msg) { let jsonStr JSON.stringify(msg); let lengthBuf Buffer.alloc(4); lengthBuf.writeUInt32LE(Buffer.byteLength(jsonStr), 0); process.stdout.write(lengthBuf); process.stdout.write(jsonStr); }实操心得调试Native Messaging非常棘手因为Chrome对宿主进程的启动和关闭管理严格。一个常见的坑是宿主进程崩溃或未及时响应会导致扩展侧连接断开。在开发时务必在Node.js宿主中添加详细的日志记录收到的原始数据和发出的数据。同时确保你的宿主应用路径在配置文件中是绝对路径并且该Node.js脚本具有可执行权限在Unix系统上需要chmod x。3.2 元素选择器的生成算法录制的“灵魂”录制是否准确90%取决于元素选择器是否健壮。一个简单的document.querySelector(‘.btn’)可能在回放时因为页面多了一个.btn而失败。一个健壮的算法通常包含以下策略按优先级降序唯一ID如果元素有id属性且该ID在页面内唯一优先使用#id。组合属性寻找元素上具有唯一性的属性组合如input[name’username’][type’text’]。智能Class组合不是简单拼接所有class而是选取那些看起来非样式性的、可能具有语义的class例如避免.mt-2 .pr-3这种纯样式类并结合标签名、属性。相对路径与兄弟节点定位当元素本身缺乏特征时可以向上查找有特征的父节点然后使用:nth-child或结合文本内容来定位。例如#form div:nth-child(2) input。XPath作为备选方案XPath表达能力更强如基于文本//button[contains(text(), ‘提交’)]但可能更脆弱文本变化、翻译导致失败。实现时需要注意去重与排序为同一个元素生成多个备选选择器并按稳定性排序。回放时按顺序尝试直到有一个成功。忽略动态类过滤掉那些可能随状态变化的类名如is-active,loading。处理Shadow DOM现代Web组件使用Shadow DOM需要特殊APIelement.shadowRoot来穿透并定位内部元素。3.3 事件的处理与优化从原始流到清晰指令用户的一连串操作会产生海量原始事件尤其是mousemove和scroll。直接全部录制会导致脚本冗长、执行慢且不稳定。优化策略包括事件去噪忽略频繁触发且对业务逻辑无影响的事件如轻微的鼠标移动。事件合并将快速连续的input事件用户打字合并为一个最终只记录输入框的完整值。将mousedownmouseup在相同元素上合并为一个click事件。等待与断言插入智能识别页面跳转、模态框弹出等场景在事件序列中自动插入“等待页面加载完成”或“等待元素可见”的语句。对于表单提交后出现的成功提示可以自动生成一个断言语句来验证。坐标与选择器互补对于某些无法用选择器可靠定位的复杂图表或Canvas绘制区域可能需要回退到基于坐标的点击。但这是最后的手段因为坐标对分辨率、窗口大小极度敏感。4. 从零搭建一个简易UI Recorder核心原型为了彻底理解架构我们动手搭建一个最简化的原型。这个原型只实现核心链路扩展录制点击事件并传递到Node.js端打印出来。4.1 Chrome扩展部分1. 项目结构simple-ui-recorder-extension/ ├── manifest.json ├── background.js ├── content.js └── devtools.html (可选简化起见我们先不用面板)2. manifest.json{ “manifest_version”: 3, “name”: “Simple UI Recorder”, “version”: “1.0”, “permissions”: [ “activeTab”, “nativeMessaging” ], “host_permissions”: [“all_urls”], “background”: { “service_worker”: “background.js” }, “content_scripts”: [ { “matches”: [“all_urls”], “js”: [“content.js”], “run_at”: “document_idle” } ], “externally_connectable”: { “ids”: [“*”] } }注意Manifest V3用service_worker替代了V2的background.scripts。nativeMessaging权限是通信关键。3. content.js// 简单的元素选择器生成函数仅作示例非常基础 function getSimpleSelector(element) { if (element.id) return #${element.id}; // 简单拼接class if (element.className) { return ${element.tagName.toLowerCase()}.${element.className.split(‘ ‘).join(‘.’)}; } return element.tagName.toLowerCase(); } // 监听页面点击事件 document.addEventListener(‘click’, function(event) { const target event.target; const selector getSimpleSelector(target); const message { type: ‘click’, selector: selector, timestamp: Date.now(), url: window.location.href }; // 发送消息给background script chrome.runtime.sendMessage(message, function(response) { console.log(‘收到后台响应:’, response); }); }, true); // 使用捕获阶段以确保捕获到所有点击4. background.js// 连接到原生宿主 let nativePort null; function connectToNativeHost() { const hostName “com.example.simple_recorder”; // 需与后续注册的名称一致 try { nativePort chrome.runtime.connectNative(hostName); console.log(‘已连接到原生宿主’); nativePort.onMessage.addListener((message) { console.log(‘收到来自宿主的信息:’, message); // 可以处理来自Node.js的响应比如控制录制状态 }); nativePort.onDisconnect.addListener(() { console.log(‘与原生宿主的连接已断开’); nativePort null; // 可以尝试重连 setTimeout(connectToNativeHost, 1000); }); } catch (error) { console.error(‘连接原生宿主失败:’, error); } } // 监听来自content script的消息 chrome.runtime.onMessage.addListener((message, sender, sendResponse) { console.log(‘后台收到消息:’, message); // 如果原生连接已建立则转发消息 if (nativePort) { nativePort.postMessage(message); sendResponse({status: ‘forwarded’}); } else { sendResponse({status: ‘native_port_not_ready’}); } return true; // 保持消息通道异步开放 }); // 扩展安装或启动时尝试连接 chrome.runtime.onStartup.addListener(connectToNativeHost); chrome.runtime.onInstalled.addListener(connectToNativeHost);4.2 Node.js原生宿主部分1. 项目结构simple-ui-recorder-host/ ├── package.json ├── host.js └── com.example.simple_recorder.json (宿主注册文件)2. host.js#!/usr/bin/env node // 注意文件开头这行告诉系统用Node.js执行 const fs require(‘fs’); // 原生消息通信协议前4字节为消息长度小端序 function readNativeMessage() { const stdin process.stdin; return new Promise((resolve) { const readLength () { let chunk stdin.read(4); if (chunk null) { setTimeout(readLength, 10); return; } const length chunk.readUInt32LE(0); const data stdin.read(length); if (data) { resolve(JSON.parse(data)); } }; readLength(); }); } function sendNativeMessage(message) { const stdout process.stdout; const jsonStr JSON.stringify(message); const lengthBuf Buffer.alloc(4); lengthBuf.writeUInt32LE(Buffer.byteLength(jsonStr), 0); stdout.write(lengthBuf); stdout.write(jsonStr); } // 主循环 (async () { console.error(‘[宿主] 原生消息宿主已启动等待连接...’); while (true) { try { const message await readNativeMessage(); console.error(‘[宿主] 收到消息:’, message); // 处理消息这里只是打印和简单回显 // 实际应用中这里应该将事件存入队列或直接处理 console.log([录制事件] ${new Date(message.timestamp).toISOString()} - ${message.type} on “${message.selector}” at ${message.url}); // 发送一个响应回扩展可选 sendNativeMessage({ received: true, eventId: message.timestamp }); } catch (error) { console.error(‘[宿主] 处理消息时出错:’, error); // 发生严重错误时退出Chrome会尝试重启 process.exit(1); } } })(); // 处理进程退出 process.on(‘SIGTERM’, () { console.error(‘[宿主] 收到终止信号退出。’); process.exit(0); });3. 宿主注册文件 (com.example.simple_recorder.json)将此文件放在Chrome原生消息宿主配置的目录下。Windows:%LOCALAPPDATA%\Google\Chrome\User Data\NativeMessagingHosts\macOS:~/Library/Application Support/Google/Chrome/NativeMessagingHosts/Linux:~/.config/google-chrome/NativeMessagingHosts/(或~/.config/chromium/)文件内容{ “name”: “com.example.simple_recorder”, “description”: “Simple UI Recorder Native Host”, “path”: “/ABSOLUTE/PATH/TO/your/project/simple-ui-recorder-host/host.js”, “type”: “stdio”, “allowed_origins”: [ “chrome-extension://YOUR_EXTENSION_ID_HERE/” ] }关键点path必须是host.js的绝对路径。allowed_origins里的扩展ID需要等你将扩展加载到Chrome后在chrome://extensions/页面查看并替换。开发时可以先使用“chrome-extension://*”不安全仅用于开发测试。确保host.js有可执行权限在Unix系统chmod x host.js。4. package.json{ “name”: “simple-ui-recorder-host”, “version”: “1.0.0”, “main”: “host.js”, “scripts”: { “start”: “node host.js” }, “dependencies”: {} }4.3 运行与测试加载扩展打开Chrome进入chrome://extensions/开启“开发者模式”点击“加载已解压的扩展程序”选择simple-ui-recorder-extension文件夹。注册宿主将com.example.simple_recorder.json配置文件放到正确的系统目录下。启动宿主可选你可以先在一个终端运行node host.js观察其启动。但更常见的是由Chrome自动启动。测试打开任意网页如百度点击页面元素。然后查看Chrome扩展的后台页面chrome://extensions/- 点击对应扩展的“背景页”或“service worker”链接的控制台看是否有日志。运行host.js的终端如果手动启动或者查看系统标准错误输出宿主进程的stderr会被Chrome捕获可在扩展后台页看到部分输出。你应该能看到格式化的点击事件日志。至此一个最核心的“录制-传输”链路就打通了。在此基础上你可以丰富选择器算法、增加更多事件类型、在Node.js端添加脚本生成逻辑逐步完善成一个真正的UI Recorder。5. 常见问题排查与实战经验分享在实际开发和使用的过程中你会遇到各种各样的问题。下面是一些典型问题及其排查思路。5.1 Chrome扩展侧常见问题问题1扩展无法安装或加载提示“不支持清单版本”或“清单文件缺失或不可读”。原因manifest.json格式错误或版本号不对。Manifest V3与V2语法有较大差异。排查检查“manifest_version”: 3。使用JSON验证工具检查manifest.json是否有语法错误如多余的逗号。确认background字段在V3中是{“service_worker”: “background.js”}而不是V2的{“scripts”: [“background.js”]}。检查文件路径是否正确所有引用的JS文件是否存在于指定位置。问题2Content Script似乎没有注入或者事件监听无效。原因content_scripts的matches模式不匹配当前页面URL或者run_at时机不对。排查检查matches字段如[“all_urls”]匹配所有HTTP/HTTPS但可能不匹配file://或Chrome内部页面。尝试将run_at从“document_idle”改为“document_start”看看是否是在DOM加载前就需要执行。在扩展管理页面查看对应扩展的“详细信息”下是否对当前标签页有“已在此网站上运行内容脚本”的提示。问题3Native Messaging连接失败后台脚本报错“无法连接到原生宿主”。原因这是最复杂的一类问题可能原因很多。排查步骤逐步进行检查宿主注册文件确认JSON文件在正确的操作系统目录下且文件名与扩展中connectNative时传入的名称完全一致包括大小写。检查路径注册文件中path指向的Node.js脚本必须是绝对路径并且该文件存在、有可执行权限。检查扩展ID注册文件中allowed_origins里的扩展ID必须与你当前加载的扩展ID完全一致。开发时每次重新加载扩展ID可能会变一个办法是使用“chrome-extension://*”仅限开发。手动测试宿主在终端直接运行宿主脚本node /path/to/host.js看是否能正常启动。然后尝试通过标准输入模拟发送一条消息看它是否能处理并响应。这可以排除脚本本身的语法或逻辑错误。查看Chrome日志Chrome浏览器本身会记录原生消息宿主的错误。在Windows上可以查看事件查看器在macOS/Linux上启动Chrome时加上--enable-logging --v1参数然后查看chrome_debug.log文件搜索native相关错误。检查防火墙/安全软件某些安全软件可能会阻止Chrome启动子进程。5.2 Node.js宿主侧常见问题问题4宿主进程启动后立即退出或者收不到消息。原因通常是宿主脚本本身有未捕获的异常或者没有按照原生消息协议读写数据。排查在脚本开始处添加process.on(‘uncaughtException’, (err) { console.error(‘未捕获异常:’, err); });来捕获错误。确保你的脚本正确处理了标准输入。协议要求先读4字节的长度再读取指定长度的消息体。顺序或解析错误会导致进程阻塞或崩溃。在脚本中大量使用console.error输出调试信息stderr这些信息有时能在扩展的后台页面控制台看到。问题5录制生成的选择器在回放时找不到元素。原因页面是动态的单页应用SPADOM在录制后发生了变化或者选择器算法不够健壮。解决增强选择器实现前面提到的多策略、备选选择器生成算法。智能等待在回放脚本中在关键操作如点击后跳转、打开弹窗后插入显式等待等待目标元素出现或页面处于稳定状态。使用更稳定的属性鼓励开发为关键测试元素添加>
UI Recorder架构解析：Chrome扩展与Node.js如何协同实现自动化测试
发布时间：2026/6/25 21:42:09
1. 项目概述UI Recorder是什么以及它为何值得深究如果你是一名前端开发者、测试工程师或者对自动化测试感兴趣那么“UI Recorder”这个名字你大概率不会陌生。简单来说它是一个用于录制用户在浏览器中的操作并自动生成可执行测试脚本的工具。听起来是不是有点像“录屏回放”没错核心逻辑确实如此但它的价值远不止于此。在敏捷开发和持续集成的今天UI自动化测试是保证产品质量、提升回归效率的关键环节。然而编写和维护UI测试脚本一直是个痛点——代码量大、维护成本高、对测试人员编程能力要求不低。UI Recorder的出现旨在通过“所见即所得”的录制方式极大地降低自动化测试的入门门槛和维护成本。但今天我们不打算只停留在“如何使用”的层面。市面上关于UI Recorder的教程已经很多了。我们真正要深挖的是它的架构。具体来说是标题点明的“Chrome扩展与Node.js的协同工作”。为什么一个录制工具需要这两种看似不相关的技术组合Chrome扩展负责什么Node.js又扮演什么角色它们之间如何通信、如何分工协作才能实现从录制到生成脚本再到执行的一整套流程理解这套架构不仅能让你在使用UI Recorder时更加得心应手排查问题更快更准更能为你自己设计类似的、需要连接浏览器前端与本地后端服务的工具时提供一套清晰、可复用的技术蓝图。这就像不仅会开车还懂发动机原理和传动系统面对故障时你就不再束手无策。2. 核心架构拆解为什么是Chrome扩展 Node.js要理解UI Recorder的架构首先要明白它要解决的核心问题如何无侵入、高保真地捕获用户在浏览器中的交互并将这些交互转化为结构化的、可编程的事件数据最终在本地生成并运行测试脚本。这个目标拆解开来就自然引出了两个主战场浏览器环境这是用户交互发生的地方。我们需要在这里监听所有用户操作——点击、输入、滚动、跳转等并获取操作目标的详细信息如DOM元素的唯一选择器、属性、坐标等。这个过程必须足够轻量、实时且不能干扰用户正常浏览。本地开发/测试环境这是处理数据、生成脚本、管理测试套件、连接其他服务如测试报告、CI/CD的地方。这里需要文件IO、进程管理、网络服务、依赖包管理等能力。现在我们来看技术选型如何匹配这两个战场。2.1 Chrome扩展的角色浏览器内的“侦察兵”与“信号兵”Chrome扩展是解决“浏览器环境”问题的绝佳选择。它由几个关键部分组成在UI Recorder中各自承担重任Content Script内容脚本这是注入到每个被录制页面的JavaScript代码。它像潜伏在页面里的“侦察兵”直接与页面DOM交互。它的核心职责是事件监听通过addEventListener监听页面的click,input,change,submit,keydown等所有用户交互事件。DOM信息提取当事件发生时内容脚本需要立刻捕获事件目标元素并计算出一个或多个能唯一、稳定定位到该元素的CSS选择器或XPath。这是录制准确性的基石。一个健壮的算法会考虑id、class、>{ “name”: “com.mycompany.uirecorder”, “description”: “UI Recorder Host”, “path”: “/usr/local/bin/uirecorder-host.js”, “type”: “stdio”, “allowed_origins”: [“chrome-extension://你的扩展ID/”] }连接建立当Chrome扩展调用chrome.runtime.connectNative(“com.mycompany.uirecorder”)时Chrome浏览器会根据名称找到配置文件并启动path指定的Node.js程序。消息格式通信双方通过stdin和stdout传递JSON消息。每条消息前4个字节是消息体的长度小端序后面紧跟JSON字符串。Node.js端需要不断读取process.stdin来获取数据并向process.stdout写入数据来响应。// Node.js宿主示例代码片段 const fs require(‘fs’); process.stdin.on(‘readable’, () { let lengthBytes process.stdin.read(4); if (!lengthBytes) return; let length lengthBytes.readUInt32LE(0); let message JSON.parse(process.stdin.read(length)); // 处理来自扩展的消息 handleMessage(message); }); function sendToExtension(msg) { let jsonStr JSON.stringify(msg); let lengthBuf Buffer.alloc(4); lengthBuf.writeUInt32LE(Buffer.byteLength(jsonStr), 0); process.stdout.write(lengthBuf); process.stdout.write(jsonStr); }实操心得调试Native Messaging非常棘手因为Chrome对宿主进程的启动和关闭管理严格。一个常见的坑是宿主进程崩溃或未及时响应会导致扩展侧连接断开。在开发时务必在Node.js宿主中添加详细的日志记录收到的原始数据和发出的数据。同时确保你的宿主应用路径在配置文件中是绝对路径并且该Node.js脚本具有可执行权限在Unix系统上需要chmod x。3.2 元素选择器的生成算法录制的“灵魂”录制是否准确90%取决于元素选择器是否健壮。一个简单的document.querySelector(‘.btn’)可能在回放时因为页面多了一个.btn而失败。一个健壮的算法通常包含以下策略按优先级降序唯一ID如果元素有id属性且该ID在页面内唯一优先使用#id。组合属性寻找元素上具有唯一性的属性组合如input[name’username’][type’text’]。智能Class组合不是简单拼接所有class而是选取那些看起来非样式性的、可能具有语义的class例如避免.mt-2 .pr-3这种纯样式类并结合标签名、属性。相对路径与兄弟节点定位当元素本身缺乏特征时可以向上查找有特征的父节点然后使用:nth-child或结合文本内容来定位。例如#form div:nth-child(2) input。XPath作为备选方案XPath表达能力更强如基于文本//button[contains(text(), ‘提交’)]但可能更脆弱文本变化、翻译导致失败。实现时需要注意去重与排序为同一个元素生成多个备选选择器并按稳定性排序。回放时按顺序尝试直到有一个成功。忽略动态类过滤掉那些可能随状态变化的类名如is-active,loading。处理Shadow DOM现代Web组件使用Shadow DOM需要特殊APIelement.shadowRoot来穿透并定位内部元素。3.3 事件的处理与优化从原始流到清晰指令用户的一连串操作会产生海量原始事件尤其是mousemove和scroll。直接全部录制会导致脚本冗长、执行慢且不稳定。优化策略包括事件去噪忽略频繁触发且对业务逻辑无影响的事件如轻微的鼠标移动。事件合并将快速连续的input事件用户打字合并为一个最终只记录输入框的完整值。将mousedownmouseup在相同元素上合并为一个click事件。等待与断言插入智能识别页面跳转、模态框弹出等场景在事件序列中自动插入“等待页面加载完成”或“等待元素可见”的语句。对于表单提交后出现的成功提示可以自动生成一个断言语句来验证。坐标与选择器互补对于某些无法用选择器可靠定位的复杂图表或Canvas绘制区域可能需要回退到基于坐标的点击。但这是最后的手段因为坐标对分辨率、窗口大小极度敏感。4. 从零搭建一个简易UI Recorder核心原型为了彻底理解架构我们动手搭建一个最简化的原型。这个原型只实现核心链路扩展录制点击事件并传递到Node.js端打印出来。4.1 Chrome扩展部分1. 项目结构simple-ui-recorder-extension/ ├── manifest.json ├── background.js ├── content.js └── devtools.html (可选简化起见我们先不用面板)2. manifest.json{ “manifest_version”: 3, “name”: “Simple UI Recorder”, “version”: “1.0”, “permissions”: [ “activeTab”, “nativeMessaging” ], “host_permissions”: [“all_urls”], “background”: { “service_worker”: “background.js” }, “content_scripts”: [ { “matches”: [“all_urls”], “js”: [“content.js”], “run_at”: “document_idle” } ], “externally_connectable”: { “ids”: [“*”] } }注意Manifest V3用service_worker替代了V2的background.scripts。nativeMessaging权限是通信关键。3. content.js// 简单的元素选择器生成函数仅作示例非常基础 function getSimpleSelector(element) { if (element.id) return #${element.id}; // 简单拼接class if (element.className) { return ${element.tagName.toLowerCase()}.${element.className.split(‘ ‘).join(‘.’)}; } return element.tagName.toLowerCase(); } // 监听页面点击事件 document.addEventListener(‘click’, function(event) { const target event.target; const selector getSimpleSelector(target); const message { type: ‘click’, selector: selector, timestamp: Date.now(), url: window.location.href }; // 发送消息给background script chrome.runtime.sendMessage(message, function(response) { console.log(‘收到后台响应:’, response); }); }, true); // 使用捕获阶段以确保捕获到所有点击4. background.js// 连接到原生宿主 let nativePort null; function connectToNativeHost() { const hostName “com.example.simple_recorder”; // 需与后续注册的名称一致 try { nativePort chrome.runtime.connectNative(hostName); console.log(‘已连接到原生宿主’); nativePort.onMessage.addListener((message) { console.log(‘收到来自宿主的信息:’, message); // 可以处理来自Node.js的响应比如控制录制状态 }); nativePort.onDisconnect.addListener(() { console.log(‘与原生宿主的连接已断开’); nativePort null; // 可以尝试重连 setTimeout(connectToNativeHost, 1000); }); } catch (error) { console.error(‘连接原生宿主失败:’, error); } } // 监听来自content script的消息 chrome.runtime.onMessage.addListener((message, sender, sendResponse) { console.log(‘后台收到消息:’, message); // 如果原生连接已建立则转发消息 if (nativePort) { nativePort.postMessage(message); sendResponse({status: ‘forwarded’}); } else { sendResponse({status: ‘native_port_not_ready’}); } return true; // 保持消息通道异步开放 }); // 扩展安装或启动时尝试连接 chrome.runtime.onStartup.addListener(connectToNativeHost); chrome.runtime.onInstalled.addListener(connectToNativeHost);4.2 Node.js原生宿主部分1. 项目结构simple-ui-recorder-host/ ├── package.json ├── host.js └── com.example.simple_recorder.json (宿主注册文件)2. host.js#!/usr/bin/env node // 注意文件开头这行告诉系统用Node.js执行 const fs require(‘fs’); // 原生消息通信协议前4字节为消息长度小端序 function readNativeMessage() { const stdin process.stdin; return new Promise((resolve) { const readLength () { let chunk stdin.read(4); if (chunk null) { setTimeout(readLength, 10); return; } const length chunk.readUInt32LE(0); const data stdin.read(length); if (data) { resolve(JSON.parse(data)); } }; readLength(); }); } function sendNativeMessage(message) { const stdout process.stdout; const jsonStr JSON.stringify(message); const lengthBuf Buffer.alloc(4); lengthBuf.writeUInt32LE(Buffer.byteLength(jsonStr), 0); stdout.write(lengthBuf); stdout.write(jsonStr); } // 主循环 (async () { console.error(‘[宿主] 原生消息宿主已启动等待连接...’); while (true) { try { const message await readNativeMessage(); console.error(‘[宿主] 收到消息:’, message); // 处理消息这里只是打印和简单回显 // 实际应用中这里应该将事件存入队列或直接处理 console.log([录制事件] ${new Date(message.timestamp).toISOString()} - ${message.type} on “${message.selector}” at ${message.url}); // 发送一个响应回扩展可选 sendNativeMessage({ received: true, eventId: message.timestamp }); } catch (error) { console.error(‘[宿主] 处理消息时出错:’, error); // 发生严重错误时退出Chrome会尝试重启 process.exit(1); } } })(); // 处理进程退出 process.on(‘SIGTERM’, () { console.error(‘[宿主] 收到终止信号退出。’); process.exit(0); });3. 宿主注册文件 (com.example.simple_recorder.json)将此文件放在Chrome原生消息宿主配置的目录下。Windows:%LOCALAPPDATA%\Google\Chrome\User Data\NativeMessagingHosts\macOS:~/Library/Application Support/Google/Chrome/NativeMessagingHosts/Linux:~/.config/google-chrome/NativeMessagingHosts/(或~/.config/chromium/)文件内容{ “name”: “com.example.simple_recorder”, “description”: “Simple UI Recorder Native Host”, “path”: “/ABSOLUTE/PATH/TO/your/project/simple-ui-recorder-host/host.js”, “type”: “stdio”, “allowed_origins”: [ “chrome-extension://YOUR_EXTENSION_ID_HERE/” ] }关键点path必须是host.js的绝对路径。allowed_origins里的扩展ID需要等你将扩展加载到Chrome后在chrome://extensions/页面查看并替换。开发时可以先使用“chrome-extension://*”不安全仅用于开发测试。确保host.js有可执行权限在Unix系统chmod x host.js。4. package.json{ “name”: “simple-ui-recorder-host”, “version”: “1.0.0”, “main”: “host.js”, “scripts”: { “start”: “node host.js” }, “dependencies”: {} }4.3 运行与测试加载扩展打开Chrome进入chrome://extensions/开启“开发者模式”点击“加载已解压的扩展程序”选择simple-ui-recorder-extension文件夹。注册宿主将com.example.simple_recorder.json配置文件放到正确的系统目录下。启动宿主可选你可以先在一个终端运行node host.js观察其启动。但更常见的是由Chrome自动启动。测试打开任意网页如百度点击页面元素。然后查看Chrome扩展的后台页面chrome://extensions/- 点击对应扩展的“背景页”或“service worker”链接的控制台看是否有日志。运行host.js的终端如果手动启动或者查看系统标准错误输出宿主进程的stderr会被Chrome捕获可在扩展后台页看到部分输出。你应该能看到格式化的点击事件日志。至此一个最核心的“录制-传输”链路就打通了。在此基础上你可以丰富选择器算法、增加更多事件类型、在Node.js端添加脚本生成逻辑逐步完善成一个真正的UI Recorder。5. 常见问题排查与实战经验分享在实际开发和使用的过程中你会遇到各种各样的问题。下面是一些典型问题及其排查思路。5.1 Chrome扩展侧常见问题问题1扩展无法安装或加载提示“不支持清单版本”或“清单文件缺失或不可读”。原因manifest.json格式错误或版本号不对。Manifest V3与V2语法有较大差异。排查检查“manifest_version”: 3。使用JSON验证工具检查manifest.json是否有语法错误如多余的逗号。确认background字段在V3中是{“service_worker”: “background.js”}而不是V2的{“scripts”: [“background.js”]}。检查文件路径是否正确所有引用的JS文件是否存在于指定位置。问题2Content Script似乎没有注入或者事件监听无效。原因content_scripts的matches模式不匹配当前页面URL或者run_at时机不对。排查检查matches字段如[“all_urls”]匹配所有HTTP/HTTPS但可能不匹配file://或Chrome内部页面。尝试将run_at从“document_idle”改为“document_start”看看是否是在DOM加载前就需要执行。在扩展管理页面查看对应扩展的“详细信息”下是否对当前标签页有“已在此网站上运行内容脚本”的提示。问题3Native Messaging连接失败后台脚本报错“无法连接到原生宿主”。原因这是最复杂的一类问题可能原因很多。排查步骤逐步进行检查宿主注册文件确认JSON文件在正确的操作系统目录下且文件名与扩展中connectNative时传入的名称完全一致包括大小写。检查路径注册文件中path指向的Node.js脚本必须是绝对路径并且该文件存在、有可执行权限。检查扩展ID注册文件中allowed_origins里的扩展ID必须与你当前加载的扩展ID完全一致。开发时每次重新加载扩展ID可能会变一个办法是使用“chrome-extension://*”仅限开发。手动测试宿主在终端直接运行宿主脚本node /path/to/host.js看是否能正常启动。然后尝试通过标准输入模拟发送一条消息看它是否能处理并响应。这可以排除脚本本身的语法或逻辑错误。查看Chrome日志Chrome浏览器本身会记录原生消息宿主的错误。在Windows上可以查看事件查看器在macOS/Linux上启动Chrome时加上--enable-logging --v1参数然后查看chrome_debug.log文件搜索native相关错误。检查防火墙/安全软件某些安全软件可能会阻止Chrome启动子进程。5.2 Node.js宿主侧常见问题问题4宿主进程启动后立即退出或者收不到消息。原因通常是宿主脚本本身有未捕获的异常或者没有按照原生消息协议读写数据。排查在脚本开始处添加process.on(‘uncaughtException’, (err) { console.error(‘未捕获异常:’, err); });来捕获错误。确保你的脚本正确处理了标准输入。协议要求先读4字节的长度再读取指定长度的消息体。顺序或解析错误会导致进程阻塞或崩溃。在脚本中大量使用console.error输出调试信息stderr这些信息有时能在扩展的后台页面控制台看到。问题5录制生成的选择器在回放时找不到元素。原因页面是动态的单页应用SPADOM在录制后发生了变化或者选择器算法不够健壮。解决增强选择器实现前面提到的多策略、备选选择器生成算法。智能等待在回放脚本中在关键操作如点击后跳转、打开弹窗后插入显式等待等待目标元素出现或页面处于稳定状态。使用更稳定的属性鼓励开发为关键测试元素添加>
