WebView Inspector 使用教程：从入门到精通

WebView Inspector 使用教程：从入门到精通

前面我介绍了 WebView Inspector 是什么，这篇手把手教你如何使用

一、快速上手

1.1 CDN 引入（最简单）

在你的 HTML 页面中添加：

<script src="https://cdn.jsdelivr.net/npm/webview-inspector/dist/webview-inspector.iife.js"></script>
<script>
  WebViewInspector.init();
</script>

刷新页面，右下角会出现一个悬浮按钮，点击即可打开调试面板。

1.2 NPM 安装（推荐）

npm install webview-inspector

// ES Module 方式
import WebViewInspector from 'webview-inspector';
WebViewInspector.init();

// CommonJS 方式
const WebViewInspector = require('webview-inspector');
WebViewInspector.init();

1.3 直接下载

从 Gitee 下载 dist/webview-inspector.iife.js，放到项目中：

<script src="./path/to/webview-inspector.iife.js"></script>
<script>
  WebViewInspector.init();
</script>

---

二、配置选项

init() 方法支持传入配置对象：

WebViewInspector.init({
  enable: true,              // 是否启用，默认 true
  position: 'bottom-right',  // 悬浮按钮位置，默认右下角
  theme: 'dark',             // 主题：dark / light
  zIndex: 999999             // z-index，确保在最上层
});

position 可选值

值	说明
'bottom-right'	右下角（默认）
'bottom-left'	左下角
'top-right'	右上角
'top-left'	左上角

theme 可选值

值	说明
'dark'	深色主题（默认）
'light'	浅色主题

---

三、三大核心功能

3.1 环境检测

点击悬浮按钮 → 选择「环境」Tab，可以看到：

设备信息

• 设备型号（iPhone 14 Pro / 小米13 等）
• 操作系统版本（iOS 17.4 / Android 14）
• 屏幕尺寸、DPR、安全区

浏览器/WebView 信息

• 浏览器类型（微信 / App内嵌 / 普通浏览器）
• WebView 类型（WKWebView / X5内核 / Chrome）
• WebView 版本
• 内核版本

微信环境特有

• 微信版本号
• 是否小程序环境

一键复制

点击底部的「复制环境信息」按钮，可以将所有信息复制到剪贴板，方便发给后端或记录到工单。

3.2 兼容性检测

点击悬浮按钮 → 选择「兼容」Tab，可以看到：

CSS 特性检测（30+项）

检测当前 WebView 是否支持：

• 布局相关：flex、grid、flex-direction、justify-content 等
• 视口单位：dvh、svh、lvh、vw、vh
• CSS 函数：var、calc、clamp
• 新特性：aspect-ratio、container queries、:focus-visible
• 颜色空间：oklch、oklab、display-p3

JS API 检测（56+项）

检测当前 WebView 是否支持：

• ES6+：Promise、async/await、Symbol、Map、Set
• 观察器：IntersectionObserver、MutationObserver、ResizeObserver
• 存储：localStorage、sessionStorage、IndexedDB
• 网络：fetch、WebSocket、EventSource
• Canvas：Canvas2D、WebGL、WebGL2
• 其他：Clipboard、Geolocation、WebShare 等

使用场景

// 检测是否支持某个特性
const compat = WebViewInspector.getCompat();

if (!compat.css.grid) {
  console.log('当前 WebView 不支持 CSS Grid，使用 flex 布局替代');
}

if (!compat.js.IntersectionObserver) {
  console.log('不支持 IntersectionObserver，使用 scroll 事件替代');
}

3.3 错误捕获

点击悬浮按钮 → 选择「错误」Tab，可以看到：

自动捕获的错误类型

1. JS 运行时错误

   throw new Error('这是一个测试错误');
   

2. Promise 未捕获错误

   Promise.reject('这是一个 Promise 错误');
   

3. 资源加载失败

   <img src="不存在的图片.jpg">
   <script src="不存在的脚本.js"></script>
   

错误信息包含

• 错误类型（ERROR / PROMISE / RESOURCE）
• 错误信息
• 完整堆栈
• 发生时间

一键复制

点击错误卡片，可以复制完整的错误信息和堆栈，方便反馈问题。

---

四、API 详解

4.1 实例方法

方法	说明	返回值
init(options?)	初始化调试工具	WebViewInspector
show()	显示悬浮按钮	void
hide()	隐藏悬浮按钮和面板	void
showPanel(tab?)	打开面板，可指定 Tab	void
getEnv()	获取环境信息对象	EnvInfo
getCompat()	获取兼容性报告对象	CompatReport
getErrors()	获取错误列表	ErrorInfo[]
clearErrors()	清空错误列表	void
refresh()	刷新所有数据	void
updateOptions(options)	更新配置	void
destroy()	销毁实例	void

4.2 编程式使用

// 获取环境信息
const env = WebViewInspector.getEnv();
console.log('设备型号:', env.device);
console.log('系统版本:', env.os);
console.log('WebView版本:', env.webview);

// 获取兼容性报告
const compat = WebViewInspector.getCompat();
console.log('支持 Grid:', compat.css.grid);
console.log('支持 IntersectionObserver:', compat.js.IntersectionObserver);

// 获取错误列表
const errors = WebViewInspector.getErrors();
console.log('错误数量:', errors.length);

// 清空错误
WebViewInspector.clearErrors();

// 刷新数据
WebViewInspector.refresh();

4.3 手动创建实例

const inspector = new WebViewInspector({
  position: 'bottom-left',
  theme: 'light'
});

inspector.show();  // 显示
inspector.hide();  // 隐藏
inspector.destroy(); // 销毁

---

五、实际使用场景

场景一：用户反馈页面有问题

传统做法

用户：页面打不开
开发：什么手机？
用户：华为
开发：什么型号？
用户：不知道
开发：什么系统？
用户：不知道
开发：...

使用 WebView Inspector

用户：页面打不开
开发：点一下右下角的放大镜按钮，点"复制环境信息"，发给我
用户：[复制了环境信息]
开发：好的，是华为 P40，鸿蒙 3.0，微信 8.0.33，我看看...

场景二：排查兼容性问题

// 在代码中检测特性支持
const compat = WebViewInspector.getCompat();

// 如果不支持 dvh，使用 vh 替代
if (!compat.css.dvh) {
  document.documentElement.style.setProperty('--vh', `${window.innerHeight * 0.01}px`);
}

// 如果不支持 IntersectionObserver，使用传统方案
if (!compat.js.IntersectionObserver) {
  // 使用 scroll 事件监听
  window.addEventListener('scroll', handleScroll);
} else {
  // 使用 IntersectionObserver
  const observer = new IntersectionObserver(callback);
  observer.observe(target);
}

场景三：线上错误监控

// 定期上报错误
setInterval(() => {
  const errors = WebViewInspector.getErrors();
  if (errors.length > 0) {
    // 上报到服务器
    fetch('/api/report', {
      method: 'POST',
      body: JSON.stringify({
        env: WebViewInspector.getEnv(),
        errors: errors
      })
    });
    // 清空已上报的错误
    WebViewInspector.clearErrors();
  }
}, 30000);

---

六、常见问题

Q1：生产环境要不要引入？

建议：

• 开发/测试环境：引入，方便调试
• 生产环境：可以引入，设置 enable: false，需要时通过代码开启

WebViewInspector.init({
  enable: location.hostname !== 'production.com' // 只在非生产环境启用
});

// 需要时可以通过代码开启
// WebViewInspector.updateOptions({ enable: true });

Q2：和其他调试工具冲突吗？

不冲突。WebView Inspector 只提供环境检测和兼容性检测，不拦截 console 或网络请求，可以和 vConsole、Eruda 同时使用。

Q3：支持哪些环境？

• iOS 10+ / Android 5+
• 微信内置浏览器
• 各类 App 内嵌 WebView
• 普通移动端浏览器

Q4：体积多大？

gzip 后 < 50KB，零依赖，非常轻量。

---

七、相关链接

• Gitee 仓库：gitee.com/chenzs_46/W…
• NPM 包：www.npmjs.com/package/web…

有问题欢迎在评论区留言，或者到 Gitee 提 Issue！

---

#WebView调试 #前端工具 #使用教程 #移动端H5