H5页面兼容性问题排查思路

因为业务需要会经常开发一些在移动设备上展示和使用的页面。但由于C端设备种类多，网络情况复杂，经常出现一些测试覆盖不到的情况，并且调试及复现非常麻烦，有时候排查一个问题并解决可能以天计数。所以当遇到不兼容问题或线上 bug 时怎么解决，该遵循怎么样的思路排查，这其实是一门学问。

把自己的排查思路及经验在此列举一二，相当于一份 debug 手册，抛砖引玉，大家也可以斧正交流。

当你凝视 BUG 时，BUG 也在凝视你

按需求写代码其实难度不大，大的是等服务正式上线，在不同终端设备运行后出现的问题如何排查和修复。经常遇到产品或者测试向开发反馈问题，很多情况下，我们需要从反馈的问题中提炼出问题表现，并能快速定位到问题出现在哪里。

这里不得不说的是反馈问题的方式，我遇到的最多的报 Bug 的方式是：“页面打不开了”。一句话中间没有包含任何有效信息，比如：是否必现？发生问题的机型设备？时间点？操作路径等等。当然不能要求所有人都可以以专业的方式提 Bug，那其实引导和分析用户的 Bug 也是开发者不能不具备的基本素质。遇到这种情况，我一般都会采用经典三问去追问反馈者：

1. 这个问题是必现么？
2. 这个问题是怎么复现的？
3. 你是什么设备？（手机系统版本，浏览器版本等）

基本这一轮问询下来，你可以对问题有一个基本的定位，首先需要明确的是问题的严重程度，这决定了你该如何解决当下的问题，如果是严重且紧急的问题，涉及所有或者大范围的用户，你可以采取回退版本/镜像的方式快速回滚；如果并不是很严重或者只是部分机型兼容性问题，那么你可以按照开发节奏有序修复。接下来，深呼吸，我们继续 debug。

**上线都会遇到各种各样的问题，这是一件再普通不过的事儿了。要保持一个冷静的心态**

心态确实很重要，Bug 是一直存在的。当你发觉可能的导致出现的问题的原因时，那么就可以去定位修复了。按照我的方式，我会根据复现的路径完整执行一遍，这里推荐一个工具：charles。它可以实现远程/本地的代码代理，你甚至可以通过它把服务器上的代码地址代理到本地（映射成本地地址）进行调试开发。

使用 Map Local 功能可以将远程文件/资源地址代理为本地文件/资源地址

另外在实际开发中，也经常用它来避免跨域问题，比如可以通过 Map Remote 功能将本地地址端口代理为远程的地址端口（或是域名）这样可以在开发中直接使用远程地址开发，绕过跨域和其他安全问题。

使用 Map Remote 功能代理本地开发地址到远程地址

charles 的其他功能如抓包等，在此就不再赘述了。遗憾的是这是一个付费软件，平替可以考虑 whistle, 是一款开源的软件，同样支持 Map Remote 和 Map Local 及抓包等功能。

当你有了代理工具，相当于就有了一个钥匙，意味着你可以把本地代码运行到实际的设备中，如果手边正好有报 Bug 的人相同的设备那更是锦上添花了。我可以在本地代码中增加断点和 log 信息，具体排查出现问题的代码语句。

因为平时涉及到的移动端开发居多，本身没办法使用类似 Chrome 浏览器内置的检查面板进行调试，所以代理工具是必要的。除此之外，还要推荐一个工具 VConsole，引入到页面后，可以实现类似 Chrome 开发者工具中的控制台界面，设置可以查看你最爱的 console.log 日志😊，同样支持查看 network 和页面元素。

VConsole 控制台面板

我这里是好的

“我这里是好的，你手机不行吧？” 基本是无数开发者津津乐道的回复，但兼容性问题的本质还是代码不够健壮。你需要确保你的代码在不同设备上有相同或者相似的体验，有些降级策略是必须要在开发时需要考虑到的。

对于机型兼容性问题，在测试时就需要考虑，比如增加一些老旧机型的验证，测试团队可能会有很多机型来供测试，一些平台也提供了云真机的服务，这里推荐一下我司的 WeTest 平台。有条件的开发者可以尝试用这些方式来验证自己网页和服务的兼容性。

就算是测试覆盖了很多设备，但是还是无法遍历所有的用户设备，前端上报就显得很必要了。上报不仅是对用户访问量相关指标的统计，还可以上报异常，错误堆栈等。常用的平台工具如 sentry，一些云服务商也提供了一些上报工具。

sentry 的上报看板界面

兼容性问题常见的错误可以分为：**样式问题**，**JS问题**。一些高级的 CSS 写法可能会在低版本的浏览器上无法正常渲染，一些高级的 JS 语法可能在低版本浏览器上报错。

还有一种常见问题就是网络问题，尤其在移动设备上尤为突出，可能用户的手持设备在访问页面时正好处于网络不佳的状态，此时页面无法正常显示，一些资源没有加载。对于这种情况没有很好的办法，用户可以自行尝试重新访问页面，另一方面页面本身也需要进行一些速度的优化，例如提升首屏的响应速度，减少首屏的资源引入（懒加载），这些优化点在此不再详叙。

同一个陷阱可能真能跳进去两次

话接上段，兼容性问题怎么避免？其实最好的方式就是在开发阶段就要考虑到你使用的写法是否具有广泛兼容性，当你拿捏不准时，可以使用 CanIUse 这个网站进行验证，比如当我不太清楚 CSS 中的 Backdrop Filter 属性兼容性时，可以查询到这个属性的兼容性如下

CanIUse 网站

可以看到在 QQ 浏览器下该属性不支持，这就需要考虑一些降级方案，比如使用图片或者半透明背景替代。

当我们认为的一些常见的属性/用法没有什么问题时，它可能在旧机型上还真无法按照我们预期正确表现，这里列举几个在开发过程中可能遇到的问题。

• border-radius 失效了？

没错，圆角属性也会失效，在低版本 IOS 中，如果存在下述情况，父元素包含一个图片子元素，并且父元素的属性如下，并且使用了 transform 属性，那么大概率是失效的。

  .parent {
    border-radius: 5px;
    overflow: hidden;
    img {
        width: 100%;
        height: 100%;
    }
  }

可以通过添加给父元素添加 transform: rotate(0) 来解决。

• 又白屏了？

在低版本 IOS 中，JS 代码使用了某个浏览器全局函数，在低版本 Safari 中（2010年之前）会出现报错（真的有人还在使用这么老的机型吗？），如下

    window.matchMedia();

对于这种情况，可以对这个低版本浏览器做单独的逻辑处理，避免调用这个 API 导致白屏。

• 诶，我的半透明遮罩呢？

在低版本的安卓手机上，如果需要覆盖一个半透明遮罩在图片上，那么图片本身需要设置 z-index: 0，这样才会正常显示遮罩。

   img {
    z-index: 0;
   }

   .mask {
    position: absolute;
    z-index: 99;
   }

结语

本文没有列举出所有的常见兼容性问题，更多提供一种问题排查思路和辅助的工具，可以作为路书和指引，即使遇到 Bug 也不要乱了阵脚，按图索骥，总有解决办法。

最后点题，AI Coding 现在像雨后春笋，你甚至可以不知道 CSS，HTML 就可以用 AI Agent 生成一份页面，但有些东西还是需要了解和掌握的。AI 应该是辅助而不是主力，别等用户给你报 Bug 时，你第一反应是：我去问问 ChatGPT。