纯HTML页面无法直接成为混合App主体，必须运行在WebView容器中并借助JSBridge与原生通信；需显式启用JavaScript、DOM存储及消息通道，严格匹配方法名与参数格式，并适配多端WebView渲染差异。
纯 HTML 页面无法直接成为混合 App 的主体，它必须运行在 WebView 容器中，并通过 JSBridge 与原生能力通信——否则就是个普通网页，连拍照、定位、跳转原生页都做不到。
WebView 初始化时必须启用 JavaScript 和 DOM 访问权限
Android WebView 默认禁用 JS，iOS WKWebView 默认不暴露 window.webkit.messageHandlers；不显式开启，document.getElementById 可能返回 null，fetch 也可能被拦截。
- Android：调用
webView.getSettings().setJavaScriptEnabled(true)，同时需设setDomStorageEnabled(true)（否则 localStorage 失效） - iOS：创建
WKWebViewConfiguration后，必须配置configuration.userContentController.add(self, name: "bridge")，否则window.webkit.messageHandlers.bridge是 undefined - 调试建议：在 H5 页面 onload 后加
console.log('JS enabled:', typeof window !== 'undefined')，避免白屏时误判逻辑错误
JSBridge 注册和调用必须严格匹配原生约定名
常见错误是 H5 调用 nativeBridge.scan()，但原生只注册了 scanCode；或传参格式不一致（如原生期望 { callbackId: "123" }，H5 却传 { cb: "123" }），导致静默失败。
- 统一约定命名：全部小写 + 下划线，如
get_location、open_native_page，避免大小写混用引发 iOS 大小写敏感问题 - 必须带唯一
callbackId字段，用于原生回调时匹配 JS Promise，否则连续调用会串回调 - 建议封装一层
callNative({ method: 'get_storage', params: { key: 'token' } })，内部自动生成并管理callbackId和 timeout 清理
页面尺寸和滚动行为在不同 WebView 中表现不一致
vh 在 iOS Safari 和大部分 Android WebView 中计算基准不同（是否含地址栏），position: fixed 在老版 WebView 中可能失效，下拉刷新触发后滚动位置丢失也很常见。
立即学习“前端免费学习笔记（深入）”；
- 避免依赖
100vh布局：改用height: 100%+ 父级display: flex; flex-direction: column更可靠 - 禁止在
body上设overflow: hidden，某些 Android WebView 会因此禁用整个页面滚动 - 监听
resize事件不如监听orientationchange稳定；横竖屏切换时，优先用window.screen.orientation.angle判断而非window.innerWidth
真正难的不是写出能跑的页面，而是让同一套 HTML 在微信 WebView、QQ 浏览器 X5、鸿蒙 SystemWebView、iOS WKWebView 和各种定制 ROM 的 WebView 里都保持交互一致——光是 input[type="file"] 的唤起逻辑，就至少要处理 4 种兼容路径。
