fanguyun/ai-skills/h5-compat-audit

H5 兼容性检查

按一个实用的兼容性基线审查 H5 页面或前端代码：安卓 6+ 设备、iPhone 7 之前机型、微信内浏览器，以及现代桌面端浏览器；不考虑 IE。

优先在真实代码和真实页面中找出具体风险，而不是只给泛泛建议。重点关注会导致渲染失败、交互异常、媒体播放问题、登录分享流程失效、上传失败、滚动异常、性能过差或布局错乱的问题。

快速流程

1. 确认审查对象：页面 URL、截图，或前端源码。
2. 采用如下兼容性基线：

• 安卓：安卓 6+，按较老的 Chrome/WebView 行为评估。
• iPhone：按 iPhone 7 之前机型对应的旧 Safari/WebKit 能力下限评估。
• 微信：同时考虑 iOS WKWebView 与 Android X5/WebView 的差异。
• 桌面端：现代 Chrome、Safari、Edge；忽略 IE。

1. 阅读 references/targets.md，确认目标设备矩阵和风险假设。
2. 阅读 references/checklist.md，只审查与当前对象相关的部分。
3. 输出结果时至少包含：

• 已兼容项
• 高风险不兼容项
• 建议的降级或改写方案
• 按平台排序的测试优先级

优先检查项

先检查这些内容，因为它们最容易在目标设备上出问题：

• 需要较新引擎的 JS 语法和 API：可选链、空值合并、Promise.finally、IntersectionObserver、ResizeObserver、URLSearchParams、fetch 的边界行为、剪贴板和分享 API。
• 旧设备支持较弱的 CSS 特性：gap、CSS Grid、position: sticky、动态视口单位、backdrop-filter、移动端 100vh、env(safe-area-inset-*)、过度依赖 aspect-ratio。面向安卓 6+ 时，样式中不要使用 gap 或 Grid 布局；使用 flex 配合子项 margin、百分比宽度或普通块布局降级。
• 布局与交互问题：底部固定栏、软键盘遮挡、嵌套滚动区、被动滚动处理、iOS 上的 overflow: scroll、点击延迟、点击高亮、变换父节点里的 position: fixed。
• 媒体与上传行为：自动播放限制、内联视频、canvas 尺寸上限、EXIF 方向、文件选择与拍照、超大图片的内存压力。
• 微信特有问题：JS-SDK 就绪时机、分享流程假设、返回和历史行为、外链点击与跳转限制（诱导、下载、中间页）、OAuth 跳转、字体缩放、viewport 怪异行为。
• 弱设备性能问题：包体过大、动画过重、图片过大、DOM 过多、图表或 canvas 过于耗性能。

检查方式

代码审查

检查构建目标、polyfill 策略、CSS/PostCSS 配置，以及高风险特性的实际使用情况。

• 检查 browserslist、Babel/Vite/esbuild 配置和 polyfill 设置。
• 在深入读实现前，先搜索不兼容语法和高风险 API。
• 优先复用仓库里已经存在的安全替代方案。
• 标出默认假设较新浏览器或只适配桌面交互的第三方库。

页面审查

如果提供了 URL 或截图，重点评估：

• 首屏渲染
• 表单可用性
• 字体缩放和文本溢出
• 滚动和 fixed 定位行为
• 媒体播放与上传
• 微信内打开后的分享、登录、支付、跳转流程

如果视觉信息不完整，要明确说明结论是推断，并列出仍需真机验证的部分。

输出格式

按严重程度分组输出问题：

• P0：大概率直接不可用或接近不可用
• P1：明显降级，上线前应补救
• P2：存在感知明显的不一致或降级不充分
• P3：低风险体验或细节问题

每条问题至少写清楚：

1. 风险点是什么
2. 影响哪些目标平台
3. 为什么会失败
4. 最小可行修复方案

结尾补一个简短回归清单，覆盖安卓 6+、老 iPhone、微信 iOS、微信 Android 和桌面端。

经验规则

• 默认采用渐进增强，而不是假设所有现代 API 都可用。
• 除微信特定问题外，优先用特性检测，而不是 UA 分支。
• 面向旧 iPhone 时，对 Safari/WebKit 行为、GPU 和内存上限采取更保守假设。
• 面向安卓时，即使同一系统版本，也要假设 WebView 行为存在碎片化。
• 不要花时间处理 IE 兼容。
• 要区分“已确认会坏”和“高概率有风险”。

参考资料

• 阅读 references/targets.md 了解支持的设备与浏览器基线。
• 阅读 references/checklist.md 获取具体检查清单与降级建议。