CapyToolkit 的定位来自一个很直接的观察很多开发者平时每天都要打开浏览器也经常要查设备状态、看网络、看传感器可这类工作通常被桌面软件垄断。浏览器原生Browser-native开发者工具和硬件诊断工具就是把这些能力直接搬到浏览器标签页里用 Web API 读取设备信息、监控性能、检测硬件状态。CapyToolkit 在标题里能同时带上 developer tools 和 hardware diagnostic tools说明它不是单纯写一个在线代码编辑器而是想覆盖开发辅助和本机硬件诊断两条线。这篇文章会围绕 CapyToolkit 这类工具的完整实现路径来写先讲 Web 平台给了什么能力再讲如何搭工程、写读取模块、处理权限和兼容性最后讲如何验证和发布。读完以后你可以用同一套思路做一个自己的浏览器原生诊断工具。1. 先理解 CapyToolkit 做的是什么以及浏览器原生工具的能力边界1.1 CapyToolkit 解决什么问题CapyToolkit 想解决的问题很具体让用户打开一个网页就完成设备状态检查不需要安装任何客户端。它适合两类场景。第一类是开发者工具场景比如检查当前浏览器的 User-Agent、CPU 线程数、内存量、网络类型、电池状态、性能指标这些信息对前端性能定位很有用。第二类是硬件诊断场景比如查看屏幕方向、传感器读数、设备位置、外接设备是否可用这部分使用的是浏览器开放的硬件访问 API。从工程角度看这类工具最大的价值不是“能展示属性”而是把浏览器安全模型、权限流程、兼容性降级和 API 生命周期管理组合在一起。很多人会误以为浏览器读不了硬件信息实际上 Web 平台已经开放了一大批接口难的是这些接口分散在不同规范里调用方式、权限要求、兼容性表现都不一致。CapyToolkit 适合做成一个聚合层把这些 API 统一成一致的诊断结果这样使用者只需要打开页面就能得到一份可读的设备报告。1.2 浏览器原生能读到的硬件与系统信息浏览器能读取的信息比很多人想象得多。下面这些 API 是 CapyToolkit 这类工具的主要数据来源能力分类主要 Web API能获取的信息典型使用场景设备基本信息navigator.userAgent、navigator.userAgentData浏览器、系统、设备型号、架构判断运行环境CPU 与内存navigator.hardwareConcurrency、navigator.deviceMemory逻辑 CPU 核数、设备内存量GB评估设备性能等级网络状态navigator.onLine、Network Information API在线状态、网络类型、连接速度、RTT、下行带宽诊断网络环境电池状态Battery Status API电量、是否充电、充电/放电剩余时间硬件状态检测传感器Accelerometer、Gyroscope、AmbientLightSensor、Magnetometer加速度、角速度、环境光、磁场移动端硬件诊断位置Geolocation API经纬度、精度设备定位屏幕与方向screen、Screen Orientation API分辨率、像素比、屏幕方向显示环境检查性能Performance API导航耗时、资源耗时、FPS 参考性能诊断外设Web Serial、Web Bluetooth、Web USB串口、蓝牙、USB 设备自动化测试、硬件调试这些 API 有一个共同点大部分都要求在安全上下文HTTPS 或 localhost中调用并且涉及敏感数据时需要用户授权。CapyToolkit 必须把这些条件变成产品逻辑的一部分而不是让用户遇到报错后看着空白页面发呆。1.3 浏览器原生与桌面壳的边界Electron、Tauri 这类桌面壳也能访问硬件Node.js 层甚至可以直接读写文件系统能访问系统 API能力比浏览器原生强得多。但 CapyToolkit 的“浏览器原生”特性决定了它不依赖桌面壳直接跑在普通浏览器里。这个选择有明确取舍优点零安装、跨平台、链接即用部署和维护成本低。代价无法访问 Node.js API、无法绕过安全上下文、每次使用都需要用户授权。限制Web Serial、Bluetooth、USB 等 API 在不同浏览器策略下有差异移动端和桌面端能力不一致。因此在做功能规划时要先问一个问题这个诊断项能纯靠浏览器 API 完成吗如果答案是否定的那就把它列为可选扩展而不是核心功能。CapyToolkit 的核心应该落在“浏览器可解释的状态”上比如网络、电量、内存、CPU 核数、传感器、性能指标这些已经足够支撑一个实用的诊断工具。2. 环境准备用 Vite TypeScript 搭出 CapyToolkit 最小工程2.1 技术选型和前置依赖实现这类工具不需要复杂框架核心是把 Web API 封装成模块并做出一套展示页面。推荐技术栈是 Vite TypeScript 轻量 UI 框架也可以直接用原生 TS。选类型时要考虑三点TypeScript 可以帮助补齐 Web API 的类型定义但部分硬件 API 在标准 DOM 类型里可能没有声明需要手动declare或扩展Navigator接口。尽量少引入 UI 框架把主要复杂度放在数据采集和状态管理上。开发时使用http://localhost即可满足安全上下文要求如果要用局域网 IP 测试浏览器会视为非安全上下文必须在 HTTPS 或 WebView 调试环境里处理。前置工具和版本建议工具用途建议Node.js运行包管理器和 Vite使用当前 LTS 版本pnpm 或 npm安装依赖统一一种即可Chrome / Edge开发调试对 Web API 支持最全手机浏览器真机传感器验证Chrome、Safari2.2 初始化 Vite 工程创建工程前先确认 Node.js 版本然后执行下面命令npm create vitelatest capytoolkit -- --template vanilla-ts cd capytoolkit npm install npm run dev这里用vanilla-ts模板不引入 Vue 或 React便于聚焦 API 逻辑。如果你更习惯框架开发也可以选择react-ts或vue-ts但下面核心模块都可以直接复用。初始化完成后项目结构大致如下capytoolkit/ ├── index.html ├── package.json ├── tsconfig.json ├── vite.config.ts └── src/ ├── main.ts ├── style.css └── components/2.3 目录结构与核心模块划分为了让诊断逻辑和页面展示分离建议把目录调整成这样src/ ├── main.ts # 入口负责初始化和渲染 ├── api/ # Web API 封装层 │ ├── device.ts # 设备基本信息 │ ├── battery.ts # 电池状态 │ ├── network.ts # 网络状态 │ ├── sensor.ts # 传感器数据 │ └── permission.ts # 权限检测与请求 ├── core/ # 诊断引擎 │ ├── collect.ts # 聚合各模块数据 │ └── diagnose.ts # 根据数据生成健康状态 ├── components/ # 页面组件 │ ├── InfoCard.ts │ ├── SensorBoard.ts │ └── PermissionBar.ts └── utils/ ├── detectSupport.ts # 能力检测 └── format.ts # 格式化展示这种划分有几个好处。第一api/目录只负责“能不能读、怎么读、拿到什么”如果 API 不支持就返回null。第二core/目录负责从原始数据生成诊断结论比如“电量 20% 且未充电”提示需要充电。第三页面组件只消费已经格式化好的数据不直接操作navigator这样后续可以方便地把同一套逻辑接入 PWA、扩展图标或桌面端。3. 核心实现从设备信息到硬件诊断的完整模块3.1 设备基础信息读取设备信息是诊断工具的基础页。至少应该覆盖平台、浏览器标识、逻辑 CPU 核数、设备内存、语言和在线状态。在src/api/device.ts里写一个getDeviceInfo函数export interface DeviceInfo { platform: string; ua: string; cpuCores: number; deviceMemory?: number; language: string; online: boolean; } export function getDeviceInfo(): DeviceInfo { const nav navigator as Navigator { userAgentData?: { platform: string; mobile: boolean; getHighEntropyValues?: (hints: string[]) PromiseRecordstring, unknown; }; }; return { platform: nav.userAgentData?.platform ?? navigator.platform ?? unknown, ua: navigator.userAgent, cpuCores: navigator.hardwareConcurrency ?? 0, deviceMemory: (nav as { deviceMemory?: number }).deviceMemory, language: navigator.language, online: navigator.onLine, }; }要点有两个。一是userAgentData是新版 Chrome 提供的结构化浏览器信息但 Safari 和 Firefox 还不支持所以要用可选链并回退到navigator.platform。二是deviceMemory不是标准 W3C 规范部分浏览器不会暴露返回undefined时前端要做“未知”处理不能展示成undefined。如果要用userAgentData.getHighEntropyValues进一步获取系统架构、移动端品牌等信息需要这样调用async function getHighEntropyDeviceInfo() { const nav navigator as Navigator { userAgentData?: { getHighEntropyValues: (hints: string[]) Promise{ architecture?: string; fullVersionList?: { brand: string; version: string }[]; model?: string; platformVersion?: string; }; }; }; if (!nav.userAgentData?.getHighEntropyValues) { return null; } try { const hints [architecture, model, platformVersion, fullVersionList]; const value await nav.userAgentData.getHighEntropyValues(hints); return { architecture: value.architecture, model: value.model, platformVersion: value.platformVersion, brandList: value.fullVersionList, }; } catch (error) { console.warn(getHighEntropyValues 调用失败, error); return null; } }这里要注意getHighEntropyValues可能返回比userAgent更精确的信息但浏览器出于隐私考虑只在用户允许navigator.userAgentData相关权限后才返回部分提示并且调用时可能抛错。真实项目里要把它作为增强信息不能用它作为主要判断依据。3.2 电池、网络与性能状态电池状态是硬件诊断工具的高频功能。Battery Status API 的使用方式如下export interface BatteryInfo { charging: boolean; level: number; chargingTime: number; dischargingTime: number; } export function isBatteryApiSupported(): boolean { return getBattery in navigator; } export async function getBatteryInfo(): PromiseBatteryInfo | null { if (!isBatteryApiSupported()) { return null; } const battery await (navigator as Navigator { getBattery: () Promise{ charging: boolean; level: number; chargingTime: number; dischargingTime: number; addEventListener: (type: string, handler: () void) void; }; }).getBattery(); return { charging: battery.charging, level: battery.level, chargingTime: battery.chargingTime Infinity ? -1 : battery.chargingTime, dischargingTime: battery.dischargingTime Infinity ? -1 : battery.dischargingTime, }; } export function watchBattery(handler: (info: BatteryInfo) void) { if (!isBatteryApiSupported()) { return () undefined; } let latest: BatteryInfo | null null; const refresh async () { const info await getBatteryInfo(); if (info (!latest || JSON.stringify(info) ! JSON.stringify(latest))) { latest info; handler(info); } }; void refresh(); battery?.addEventListener?.(levelchange, refresh); battery?.addEventListener?.(chargingchange, refresh); return () { battery?.removeEventListener?.(levelchange, refresh); battery?.removeEventListener?.(chargingchange, refresh); }; }网络状态可以用 Network Information API 获取更丰富的数据export interface NetworkInfo { online: boolean; effectiveType?: string; downlink?: number; rtt?: number; saveData?: boolean; } export function getNetworkInfo(): NetworkInfo { const conn (navigator as Navigator { connection?: NetworkInformation; }).connection; return { online: navigator.onLine, effectiveType: conn?.effectiveType, downlink: conn?.downlink, rtt: conn?.rtt, saveData: conn?.saveData, }; }这里有两个容易踩坑的地方。第一chargeTime和dischargingTime在部分浏览器里可能是Infinity展示成Infinity没有意义要统一转换成可读文案。第二Network Information API 在不同浏览器里属性名不同早期 Chrome 还可能存在navigator.mozConnection这种带前缀的写法所以封装层要负责兼容页面层不要感知差异。3.3 传感器硬件数据采集传感器是 CapyToolkit 作为硬件诊断工具最能体现差异化的模块。常见传感器包括加速度计、陀螺仪、环境光传感器。以加速度计为例export function startAccelerometer(handler: (value: { x: number; y: number; z: number }) void): () void { if (!(Accelerometer in window)) { handler({ x: 0, y: 0, z: 0 }); return () undefined; } const sensor new (window as unknown as { Accelerometer: new (options: { frequency: number }) { x: number | null; y: number | null; z: number | null; start: () void; stop: () void; addEventListener: (type: reading | error, handler: (event: Event) void) void; removeEventListener: (type: reading | error, handler: (event: Event) void) void; }; }).Accelerometer({ frequency: 10 }); const onReading () { handler({ x: sensor.x ?? 0, y: sensor.y ?? 0, z: sensor.z ?? 0, }); }; const onError (error: Event) { console.warn(Accelerometer error, error); }; sensor.addEventListener(reading, onReading); sensor.addEventListener(error, onError); sensor.start(); return () { sensor.stop(); sensor.removeEventListener(reading, onReading); sensor.removeEventListener(error, onError); }; }传感器模块有两个重点。第一Accelerometer的x、y、z在某些平台会是null空值统一处理成0只是示例生产环境应该保留为“不可用”状态避免诊断误判。第二传感器创建后必须start()组件卸载时要调用返回的 stop 函数否则会出现“停止记录后传感器仍在运行”的告警。CapyToolkit 里的所有数据采集函数都应该返回“停止监听”的回调函数这样页面组件可以用统一方式管理生命周期。3.4 诊断结果展示逻辑原始数据和诊断结论是两件事。CapyToolkit 应该在core/collect.ts中把所有模块采集结果聚合起来再交给页面展示export interface DeviceReport { device: DeviceInfo; battery: BatteryInfo | null; network: NetworkInfo; sensors: { accelerometer: { x: number; y: number; z: number }; supported: boolean; }; collectedAt: number; } export async function collectDeviceReport(): PromiseDeviceReport { const [battery] await Promise.all([ getBatteryInfo(), ]); return { device: getDeviceInfo(), battery, network: getNetworkInfo(), sensors: { accelerometer: { x: 0, y: 0, z: 0 }, supported: Accelerometer in window, }, collectedAt: Date.now(), }; }页面组件只负责把DeviceReport渲染出来并给每个诊断项一个状态正常、警告、不支持、未知。比如电量低于 20% 且未充电可以标为警告deviceMemory为undefined标为未知传感器 API 不存在标为不支持。这种“展示层不直接调用 API”的设计比在组件里到处写navigator.xxx更容易维护和扩展。4. 权限模型安全上下文、授权流程与兼容性降级4.1 为什么硬件 API 需要安全上下文浏览器原生硬件诊断工具最大的工程约束来自权限模型。浏览器安全模型规定涉及设备信息和硬件访问的 API 必须在安全上下文Secure Context中可用。安全上下文基本可以理解为https://或http://localhost。为什么这样设计原因不是为了刁难开发者而是防止网站在用户不知情的情况下读取设备信息、启动传感器、获取位置。如果普通的 HTTP 网页也能调用传感器和串口那在公共 WiFi 环境下中间人攻击者就能构造恶意页面读取用户设备状态。CapyToolkit 在开发阶段用 localhost 没有问题但一旦部署到真实环境就必须启用 HTTPS。这是很多开发者遇到“本地能运行、部署后报 SecurityError”的根本原因。另一个容易被忽略的是 iframe 嵌套。如果你的工具被嵌入到第三方页面而第三方页面不是 HTTPS或者没有配置正确的 Permissions Policy也会出现权限被阻断的问题。4.2 Permissions API 与用户授权流程浏览器对硬件 API 的授权方式不统一。一部分 API 在调用时才弹出权限提示另一部分可以在调用前用 Permissions API 查询状态。对于 CapyToolkit 这类工具建议在页面加载后先做一次权限状态扫描把结果分成三类granted可以直接调用。prompt需要用户点击某个按钮后调用会触发浏览器权限弹窗。denied用户已拒绝或者浏览器策略禁止不能再次弹窗只能引导用户去浏览器设置里修改。示例代码如下export async function getPermissionState(permissionName: PermissionName): PromisePermissionState | null { if (!navigator.permissions?.query) { return null; } try { const result await navigator.permissions.query({ name: permissionName }); return result.state; } catch (error) { console.warn(权限查询失败:, permissionName, error); return null; } }但要特别注意Permissions API 支持的PermissionName列表并不与全部硬件 API 对齐。比如 Geolocation 支持geolocationCamera 支持camera传感器在 Chrome 中可以用accelerometer查询但 Web Serial、Web Bluetooth 在很多浏览器里并不支持通过navigator.permissions查询。所以权限方案必须走“先查询、查询不到就调用时捕获异常”的双保险。4.3 兼容性检测与降级策略不同浏览器对同一个 API 的可用性差异很大。CapyToolkit 的降级策略应该遵循一个原则没有 API 就显示“不支持”不显示错误堆栈有 API 但缺权限就显示“需要授权”有权限但调用失败才显示错误信息。下面是一个能力检测工具函数export function isApiSupported(name: string): boolean { switch (name) { case battery: return getBattery in navigator; case accelerometer: return Accelerometer in window; case geolocation: return geolocation in navigator; case serial: return serial in navigator; case bluetooth: return bluetooth in navigator; default: return false; } }能力检测之后应该在页面顶部展示一张“支持矩阵”告诉用户当前浏览器支持哪些诊断项、哪些被禁用。这样用户不会因为看不到某个模块而认为工具坏了。降级策略还可以配合本地缓存读取过一次的设备基础信息可以缓存一段时间减少重复调用但涉及隐私的数据如位置、传感器不能随意缓存必须有明确的保留期限。5. 运行验证与典型问题排查5.1 本地开发验证开发环境先启动 Vitenpm run devChrome 打开http://localhost:5173。打开 DevTools Console 面板确认没有 TypeScript 报错和未捕获的异常。然后检查网络面板看看是否有权限请求被拒绝。验证重点不是“页面渲染出来了”而是每个模块的数据是否正确设备信息检查hardwareConcurrency是否与你的 CPU 逻辑核数一致。电池在台式机上通常不充电显示电量为 100% 或不可用在笔记本和手机上应该能读到真实电量。网络切换 Wi-Fi 和移动网络观察effectiveType是否变化。传感器在手机上晃动设备加速度计数值是否发生变化。如果在桌面 Chrome 上测试传感器默认可能没有传感器数据需要用 DevTools 模拟。5.2 使用 DevTools 模拟硬件和网络状态Chrome DevTools 提供了几个对 CapyToolkit 很实用的模拟面板面板模拟能力适合验证的模块Elements Sensors模拟地理位置、设备方向、加速度、触屏传感器、定位Network Throttling模拟 Slow 3G、Fast 3G、离线网络状态、在线状态Performance录制性能数据性能诊断Console查看权限和 API 调用报错全部模块传感器模拟的典型路径是DevTools 面板点击左上角三个点选 More Tools Sensors然后在 Location 和 Sensors 区域输入模拟值。此时页面上Accelerometer和Geolocation的数据会变成模拟值。这个功能特别适合在桌面开发时检查前端渲染逻辑但它不能完全替代真机验证因为真实传感器会有噪声、频率波动和权限差异。5.3 典型错误与排查链路浏览器原生硬件诊断工具容易遇到几类报错。下面按“现象 - 原因 - 检查方式 - 处理建议”整理问题现象常见原因检查方式处理建议SecurityError: Permission denied当前环境不是 HTTPS或页面嵌入在非安全 iframe 中看 Console 报错来源检查地址栏和 frame 上下文使用 HTTPS 部署开发时用 localhost 而非局域网 IPNotAllowedError: Permission denied用户拒绝了权限请求或浏览器策略拦截调用navigator.permissions.query查看状态看浏览器地址栏权限图标引导用户点击权限图标在设置里允许不要反复弹窗请求NotReadableError: Cannot read data设备被其他应用占用或浏览器无法访问硬件检查是否有其他软件占用传感器、摄像头、串口关闭占用程序重新调用提示用户检查硬件连接NotFoundError: Device not found浏览器没有找到对应硬件设备确认设备已连接检查浏览器是否有设备权限提示用户重新连接设备并提供“刷新设备列表”按钮API 不被支持浏览器版本过旧或 API 未实现使用能力检测函数输出支持矩阵降级为“不支持”状态并提示用户更换支持的浏览器排查顺序要固定不要一看到报错就改代码。先用能力检测判断浏览器是否支持再用权限查询判断用户是否授权最后才检查硬件设备是否存在。日志是关键建议在封装层里记录apiName、error.name、error.message和permissionState这四种信息组合起来基本能定位 90% 的问题。6. 从本地工具到生产发布最佳实践与扩展方向6.1 学习环境与生产环境的差异CapyToolkit 在本地跑通和生产环境真正能用之间还有很长一段距离。下面这张表格值得放在项目文档里维度学习环境生产环境访问协议http://localhost必须 HTTPS并配置 HTTPS 重定向权限说明可以假设用户理解浏览器权限弹窗需要前置引导页解释为什么需要权限数据展示直接输出原始值格式化、脱敏、状态标记错误处理控制台输出错误用户可见的错误提示 日志采集缓存策略可以少缓存需要明确的缓存策略和清理机制测试范围只测桌面 Chrome桌面 Chrome、Edge、Firefox、Safari、Android WebView、iOS Safari 等不建议直接把 localhost 开发环境下能用的版本原样部署到公网。至少要增加权限前置说明、错误兜底和 HTTPS 配置。否则用户第一次打开看到一个权限弹窗不知道发生了什么可能直接关掉页面。6.2 PWA、离线和日志CapyToolkit 很适合做成 PWA。原因是硬件诊断工具通常需要快速打开而且离线时也应该能查看上次的诊断结果。PWA 的最低方案是注册 Service Worker 缓存静态资源和最近一份设备报告。这里要注意千万不要把传感器读数、地理位置这类实时数据缓存到 Service Worker只缓存“设备基础信息”和“诊断结论文本”这类非敏感内容。日志设计建议保持简单。不要直接把navigator.userAgent和传感器数据无差别上传。可以在页面里维护一个诊断日志对象包含时间戳、API 名称、是否支持、权限状态、错误名称、短错误信息。只有发生异常时日志才会上报同时把设备型号和浏览器信息做脱敏处理。6.3 隐私与合规浏览器原生硬件诊断工具天然涉及用户隐私。地理坐标、电池状态、传感器数据都属于敏感信息。最佳做法是采集前明确告知用户用途使用引导页而不是直接弹权限框。只在用户主动点击“开始诊断”时采集不在后台静默采集。传感器数据只用于本次会话展示不上传确实需要上传时必须先取得用户同意。提供“停止所有采集”按钮全局停止后所有事件监听和定时器都要清理。代码里避免记录和展示不必要的用户 Agent 高熵信息。6.4 可扩展方向与上线前检查清单CapyToolkit 扩展到更深入的外设调试时可以考虑引入 Web Serial、Web Bluetooth、Web USB扩展方向适用场景浏览器要求注意点Web Serial串口设备调试、开发板通信、协议分析Chrome、Edge 支持较好必须 HTTPS端口选择依赖用户授权Web BluetoothBLE 外设调试、蓝牙传感器Chrome、Android 支持较好需要用户点击触发设备选择Web USBUSB 设备识别、固件信息读取Chrome、Edge 支持较好驱动兼容性问题较多Windows 表现好File System Access API读取本地配置文件、保存诊断报告Chromium 系支持较好文件句柄需用户授权关闭页面后需要重新授权上线前建议使用下面这份检查清单[ ] 全部页面均通过 HTTPS 访问且存在 localhost 之外的验证环境。[ ] 权限弹窗前置说明清楚用户清楚知道每个权限用途。[ ] 所有硬件 API 都做了能力检测不支持时显示“不可用”而非报错。[ ] 所有采集回调都返回清理函数组件卸载或停止诊断时能关闭监听。[ ] 电池、网络、传感器数据展示有单位、粒度和更新频率说明。[ ] 日志采集不包含敏感原始数据错误信息不含完整用户字符串。[ ] 在 Chrome、Edge、Safari、Firefox 和移动端浏览器各验证一次。[ ] 有明确的“停止采集”入口用户可以一键关闭所有硬件访问。[ ] Service Worker 缓存策略不缓存实时传感器数据。[ ] 文档里写明浏览器兼容矩阵和已知限制。浏览器原生工具是一种成本低、分发快的产品形态但它的成功依赖工程上的克制。CapyToolkit 真正值得学习的地方不是堆了哪些 API而是如何把这些 API 放进统一的数据采集、权限管理和错误处理框架里。如果要给所有实践建议排优先级我的建议是先把 HTTPS 和权限说明做扎实再把设备信息面板做完整最后再考虑接入 Web Serial 这类深水区能力。浏览器硬件诊断工具的上限由用户授权意愿决定而下限由降级策略和错误处理质量决定。先保证每个诊断项在“不支持”“未授权”“有故障”三种状态下都有清晰表达再谈更多硬件能力。