1. 项目背景与核心需求拆解在 iOS 开发中用 WKWebView 加载 HTML 内容是一个非常高频的场景。无论是展示服务端返回的富文本协议、内嵌活动页面还是加载本地打包的静态页面开发者几乎都会遇到同一个问题页面在手机上显示得乱七八糟。要么内容宽度溢出屏幕要么图片撑破容器要么视频播放时全屏乱转要么用户长按弹出选择菜单甚至触发 3D Touch 预览体验非常割裂。这个项目的核心目标就是解决 WKWebView 加载 HTML 时的四类典型适配问题屏幕宽度自适应、图片自适应、视频播放自适应、长按事件禁用。它不是一个庞大的框架而是一套可以直接复用的配置方案和注入脚本组合。适合所有正在做 iOS 原生与 Web 混合开发的工程师尤其是那些需要快速把 H5 内容嵌入 App、又不想引入重型前端框架的场景。我做过好几个类似需求从资讯类 App 的正文渲染到电商详情页的图文混排再到教育类 App 的课件展示几乎每次都会踩一遍这些坑。有些问题看起来简单但真正要做到“稳”需要理解 WKWebView 的渲染机制、Viewport 的解析规则、以及 JavaScript 注入的时机。下面我会把这套方案完整拆开从设计思路到实操细节再到问题排查全部讲清楚。2. 整体方案设计与技术选型考量2.1 为什么选择 WKWebView 而不是 UIWebView这个问题其实已经没什么悬念了。UIWebView 从 iOS 8 开始就被 WKWebView 取代后者在性能、内存占用、JavaScript 引擎效率上都有明显优势。更重要的是WKWebView 提供了更完善的代理方法和配置项比如WKUserContentController可以注入脚本WKNavigationDelegate可以精细控制加载流程。对于需要做自适应和事件拦截的场景这些能力是必需的。不过 WKWebView 也有自己的脾气。它运行在独立的进程中JavaScript 执行和原生通信是异步的注入时机不对就会失效。所以方案设计的第一原则是所有配置必须在 WebView 初始化阶段完成所有脚本必须在页面加载前注入。2.2 自适应方案的核心思路自适应这件事本质上是在解决“HTML 不知道手机屏幕有多宽”的问题。传统 PC 页面默认按 980px 宽度渲染放到手机上就会缩小到看不清。解决方案是在 HTML 的head里插入一个正确的 viewport meta 标签meta nameviewport contentwidthdevice-width, initial-scale1.0, maximum-scale1.0, user-scalableno但问题在于服务端返回的 HTML 往往没有这个标签或者标签写得不对。我们不可能要求后端为每个页面都适配移动端所以最稳妥的做法是在原生侧通过 JavaScript 注入动态修改或创建 viewport meta 标签。图片自适应也是同理。很多富文本编辑器生成的img标签带着固定的 width 和 height 属性直接渲染就会溢出。我们需要在页面加载完成后遍历所有图片把它们的最大宽度限制为容器宽度高度设为 auto。视频自适应稍微复杂一点。video标签在不同 iOS 版本上的表现不一致有些会自动全屏有些会内联播放。我们需要同时处理playsinline属性和webkit-playsinline属性并且用 CSS 限制视频容器的宽度。2.3 禁用长按事件的实现路径长按事件在 WKWebView 里默认会触发文本选择、链接预览、图片保存菜单等。禁用它的方式有几种一是通过 CSS 设置-webkit-touch-callout: none和-webkit-user-select: none二是通过 JavaScript 监听contextmenu事件并阻止默认行为三是在原生侧通过WKWebView的configuration做一些限制。我实测下来CSS JavaScript 组合拳最稳。CSS 负责静态样式层面的禁用JavaScript 负责动态拦截。两者缺一不可因为有些长按行为是系统级别的单靠 CSS 拦不住。3. 核心细节解析与实操要点3.1 Viewport 注入的时机与写法注入 viewport 的脚本必须在document开始加载时执行也就是在WKUserScript的injectionTime设置为.atDocumentStart。如果等到.atDocumentEnd才注入页面可能已经按默认宽度渲染了一遍会出现闪烁或布局跳动。脚本内容大概是这样(function() { var meta document.querySelector(meta[nameviewport]); if (!meta) { meta document.createElement(meta); meta.name viewport; document.head.appendChild(meta); } meta.content widthdevice-width, initial-scale1.0, maximum-scale1.0, user-scalableno; })();这里有个细节user-scalableno可以禁止用户双指缩放但有些产品经理会要求允许缩放。如果允许缩放就把maximum-scale设大一点比如 5.0。另外initial-scale1.0是必须的否则页面可能以 0.5 倍缩放显示。注意如果 HTML 本身已经有 viewport 标签直接覆盖 content 属性即可不要重复创建否则会出现多个 viewport 标签浏览器解析行为不可预测。3.2 图片自适应的两种策略图片自适应有两种做法一种是纯 CSS一种是 JavaScript 遍历。纯 CSS 的写法是img { max-width: 100% !important; height: auto !important; }但这种方式有个问题如果图片本身有内联的width和height属性CSS 的!important可以覆盖但某些老旧的 HTML 结构里图片可能被包裹在固定宽度的table或div里这时候单纯限制图片宽度不够还需要处理父容器。所以我通常会在.atDocumentEnd时机再注入一段 JavaScript做更彻底的处理(function() { var images document.querySelectorAll(img); var maxWidth document.documentElement.clientWidth; for (var i 0; i images.length; i) { var img images[i]; img.style.maxWidth 100%; img.style.height auto; img.style.display block; img.style.margin 0 auto; if (img.naturalWidth maxWidth) { img.style.width 100%; } } })();这段脚本的关键点在于先判断图片的原始宽度是否超过屏幕宽度如果超过就强制设为 100%否则保持原样。这样可以避免小图被拉伸模糊。3.3 视频播放自适应的关键属性视频这块iOS 10 以后支持playsinline属性可以让视频在页面内播放而不是自动全屏。但为了兼容更早的版本还需要加上webkit-playsinline。完整的video标签写法是video srcxxx.mp4 playsinline webkit-playsinline controls preloadmetadata/video如果 HTML 里的视频标签没有这些属性我们同样可以通过 JavaScript 动态添加(function() { var videos document.querySelectorAll(video); for (var i 0; i videos.length; i) { var video videos[i]; video.setAttribute(playsinline, ); video.setAttribute(webkit-playsinline, ); video.setAttribute(controls, ); video.style.maxWidth 100%; video.style.height auto; } })();另外在原生侧初始化 WKWebView 时configuration.allowsInlineMediaPlayback true是必须设置的否则playsinline属性不生效。3.4 禁用长按事件的完整方案禁用长按需要从三个层面入手第一层CSS 禁用选择与呼出菜单* { -webkit-touch-callout: none; -webkit-user-select: none; user-select: none; }-webkit-touch-callout控制的是长按链接或图片时弹出的系统菜单-webkit-user-select控制的是文本选择。两个都设为 none基本能覆盖大部分场景。第二层JavaScript 拦截 contextmenu 事件document.addEventListener(contextmenu, function(e) { e.preventDefault(); return false; });这个事件在 iOS 上对应的是长按操作阻止默认行为可以进一步确保不弹出菜单。第三层原生侧禁用 3D Touch 预览在WKWebView的WKNavigationDelegate里实现webView(_:contextMenuConfigurationForElement:completionHandler:)方法并返回 nil可以禁用链接预览。不过这个方法只在 iOS 13 以上可用低版本需要另外处理。实操心得如果页面里有输入框-webkit-user-select: none会导致用户无法选择文本进行复制粘贴。这时候需要单独给input和textarea设置-webkit-user-select: text把选择能力还回来。4. 完整实操流程与核心代码实现4.1 WebView 初始化配置先看原生侧的初始化代码。这里我用 Swift 写一个完整的配置示例import WebKit class WebViewController: UIViewController { var webView: WKWebView! override func viewDidLoad() { super.viewDidLoad() let configuration WKWebViewConfiguration() configuration.allowsInlineMediaPlayback true configuration.mediaTypesRequiringUserActionForPlayback [] let userContentController WKUserContentController() userContentController.addUserScript(viewportScript()) userContentController.addUserScript(imageAdaptScript()) userContentController.addUserScript(videoAdaptScript()) userContentController.addUserScript(disableLongPressScript()) configuration.userContentController userContentController webView WKWebView(frame: view.bounds, configuration: configuration) webView.navigationDelegate self webView.scrollView.bounces false webView.scrollView.showsHorizontalScrollIndicator false view.addSubview(webView) } }这里有几个关键点allowsInlineMediaPlayback必须为 truemediaTypesRequiringUserActionForPlayback设为空数组表示视频可以自动播放如果产品要求手动播放就保留默认值。scrollView.bounces false可以避免页面滚动到顶部或底部时的回弹效果让体验更接近原生。4.2 四个注入脚本的完整实现Viewport 脚本atDocumentStartfunc viewportScript() - WKUserScript { let source (function() { var meta document.querySelector(meta[nameviewport]); if (!meta) { meta document.createElement(meta); meta.name viewport; document.head.appendChild(meta); } meta.content widthdevice-width, initial-scale1.0, maximum-scale1.0, user-scalableno; })(); return WKUserScript(source: source, injectionTime: .atDocumentStart, forMainFrameOnly: true) }图片自适应脚本atDocumentEndfunc imageAdaptScript() - WKUserScript { let source (function() { var maxWidth document.documentElement.clientWidth; var images document.querySelectorAll(img); for (var i 0; i images.length; i) { var img images[i]; img.style.maxWidth 100%; img.style.height auto; img.style.display block; img.style.margin 8px auto; if (img.naturalWidth maxWidth) { img.style.width 100%; } } })(); return WKUserScript(source: source, injectionTime: .atDocumentEnd, forMainFrameOnly: true) }视频自适应脚本atDocumentEndfunc videoAdaptScript() - WKUserScript { let source (function() { var videos document.querySelectorAll(video); for (var i 0; i videos.length; i) { var video videos[i]; video.setAttribute(playsinline, ); video.setAttribute(webkit-playsinline, ); video.setAttribute(controls, ); video.style.maxWidth 100%; video.style.height auto; video.style.display block; video.style.margin 8px auto; } })(); return WKUserScript(source: source, injectionTime: .atDocumentEnd, forMainFrameOnly: true) }禁用长按脚本atDocumentEndfunc disableLongPressScript() - WKUserScript { let source (function() { document.addEventListener(contextmenu, function(e) { e.preventDefault(); return false; }); var style document.createElement(style); style.innerHTML * { -webkit-touch-callout: none; -webkit-user-select: none; user-select: none; } input, textarea { -webkit-user-select: text; user-select: text; }; document.head.appendChild(style); })(); return WKUserScript(source: source, injectionTime: .atDocumentEnd, forMainFrameOnly: true) }4.3 加载 HTML 的两种方式加载远程 URLif let url URL(string: https://example.com/article) { let request URLRequest(url: url) webView.load(request) }加载本地 HTML 字符串let htmlString htmlhead/headbodyh1标题/h1p内容/p/body/html webView.loadHTMLString(htmlString, baseURL: nil)如果是加载本地 HTML 字符串baseURL传 nil 的话图片和视频的相对路径会失效。如果 HTML 里有本地资源引用需要传一个正确的 baseURL比如 Bundle 的路径。4.4 处理页面内跳转与新窗口WKWebView 默认会在当前 WebView 里打开所有链接。如果页面里有target_blank的链接需要实现WKUIDelegate的webView(_:createWebViewWith:for:windowFeatures:)方法否则点击没反应。extension WebViewController: WKUIDelegate { func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) - WKWebView? { if navigationAction.targetFrame nil { webView.load(navigationAction.request) } return nil } }这段代码的作用是如果链接要求在新窗口打开就直接在当前 WebView 加载避免创建新的 WebView 实例。5. 常见问题与排查技巧实录5.1 注入脚本不生效的排查思路这是最常见的问题。脚本写好了但页面加载后没有任何变化。排查顺序如下排查项检查方法常见原因注入时机确认injectionTime设置正确viewport 必须用.atDocumentStart其他用.atDocumentEnd主框架限制检查forMainFrameOnly参数如果页面有 iframe设为 true 会导致 iframe 内不生效脚本语法在 Safari 开发者工具里看控制台报错字符串转义问题、ES6 语法兼容性问题页面加载方式确认是loadHTMLString还是loadloadHTMLString时 baseURL 为 nil 可能导致部分脚本行为异常缓存问题清除 WKWebView 缓存后重试旧缓存页面可能没有执行新脚本我踩过最坑的一次是脚本里用了let和const结果在 iOS 9 的机器上直接报语法错误整个脚本不执行。后来全部改成var才解决。虽然现在 iOS 9 已经很少了但如果你的 App 还要兼容老系统这一点必须注意。5.2 图片宽度自适应的边界情况有些图片是 base64 编码的内联图片naturalWidth属性在图片未完全解码时可能是 0。这时候判断img.naturalWidth maxWidth会失效。解决方案是监听图片的load事件在加载完成后再做宽度判断img.addEventListener(load, function() { if (this.naturalWidth maxWidth) { this.style.width 100%; } });另外如果图片本身是 SVG 格式naturalWidth可能返回 0 或 undefined这时候直接用max-width: 100%就够了不需要额外判断。5.3 视频播放的兼容性坑iOS 上视频播放有几个经典问题问题一视频自动全屏无法内联播放。原因是allowsInlineMediaPlayback没有设为 true或者playsinline属性没有正确添加。两个条件必须同时满足。问题二视频有声音但画面黑屏。这种情况通常是视频编码格式不支持。iOS 对 H.264 支持最好H.265 需要 iOS 11 以上VP9 需要 iOS 14 以上。如果视频源是 WebM 格式iOS 原生不支持需要转码。问题三视频播放时页面滚动卡顿。这是 WKWebView 的渲染机制导致的视频播放时会占用大量 GPU 资源。解决方案是限制同时播放的视频数量或者在视频播放时暂停其他动画。5.4 长按禁用后的副作用处理禁用长按后最直接的副作用是用户无法复制文本了。如果产品要求允许复制就不能全局禁用-webkit-user-select而是只针对图片和链接禁用。我的做法是给img和a标签单独设置-webkit-touch-callout: none文本区域保持可选。这样既能防止图片长按弹出保存菜单又不影响用户复制文字。img, a { -webkit-touch-callout: none; }另外如果页面里有contenteditable的富文本编辑器-webkit-user-select: none会导致无法编辑。这时候需要给[contenteditable]元素单独设置-webkit-user-select: text。5.5 页面高度与滚动问题WKWebView 的内容高度是动态的如果外层用 UITableView 或 UIScrollView 包裹需要监听scrollView.contentSize的变化来调整高度。可以在webView(_:didFinish:)里通过 JavaScript 获取document.body.scrollHeight然后更新约束。document.body.scrollHeight但要注意图片加载完成后页面高度会变化所以最好在图片的load事件里也触发一次高度更新。我通常会用setTimeout延迟 0.3 秒再获取一次高度确保所有图片都渲染完毕。6. 性能优化与进阶技巧6.1 减少脚本注入的性能开销四个脚本分别在.atDocumentStart和.atDocumentEnd注入每次页面加载都会执行。如果页面内容很多querySelectorAll遍历所有图片和视频会有性能损耗。优化方式是只在必要时执行遍历比如先判断document.images.length 0再执行。另外可以把多个.atDocumentEnd的脚本合并成一个减少 JavaScript 上下文的切换开销。合并后的脚本大概长这样(function() { // 图片自适应 // 视频自适应 // 禁用长按 })();6.2 使用 WKContentRuleList 拦截资源如果页面里有大量第三方广告或跟踪脚本可以用WKContentRuleList在原生侧拦截减少页面加载时间。规则用 JSON 格式定义比如拦截所有.gif图片[{ trigger: {url-filter: .*\\.gif}, action: {type: block} }]这种方式比 JavaScript 注入更高效因为拦截发生在网络层不会消耗 WebView 的渲染资源。6.3 内存管理与 WebView 复用WKWebView 的内存占用比 UIWebView 低但如果频繁创建和销毁仍然会导致内存峰值。在列表页里如果每个 cell 都嵌一个 WebView滑动时会非常卡顿。解决方案是复用 WebView 实例或者用WKProcessPool共享进程池。let processPool WKProcessPool() configuration.processPool processPool不过WKProcessPool在 iOS 15 以后已经被标记为废弃新版本系统会自动管理进程池不需要手动设置。6.4 调试技巧Safari 开发者工具WKWebView 支持 Safari 的 Web Inspector可以在 Mac 上直接调试 iOS 设备里的 WebView。开启方式设置 Safari 高级 网页检查器。然后在 Mac 的 Safari 里开发菜单下会显示连接的设备。调试时最常用的功能是控制台和元素检查。控制台可以看 JavaScript 报错元素检查可以看注入的样式是否生效。我每次遇到脚本不生效的问题第一件事就是打开控制台看有没有报错。实操心得如果 Safari 开发者工具里看不到你的 WebView检查一下 App 是否在 Debug 模式下运行。Release 包默认不允许调试需要手动开启isInspectable属性iOS 16.4 以上。7. 不同场景下的方案调整建议7.1 资讯类 App 的正文渲染资讯类 App 的 HTML 通常来自服务端富文本编辑器结构比较规范。重点处理图片自适应和字体大小。可以在 viewport 脚本里额外注入一段设置font-size的代码让正文字号跟随系统设置document.documentElement.style.fontSize 17px;如果支持夜间模式还需要注入 CSS 变量来切换背景色和文字颜色。7.2 电商详情页的图文混排电商详情页的图片通常有固定的宽高比而且很多是懒加载的。除了基本的自适应处理还需要监听图片的load事件来更新页面高度。另外详情页里可能有视频介绍需要确保视频不自动播放避免消耗用户流量。7.3 教育类 App 的课件展示课件页面通常包含复杂的交互元素比如拖拽、点击答题等。禁用长按的时候要特别小心不能把正常的点击事件也禁用了。我的做法是只禁用contextmenu事件不全局设置-webkit-user-select: none而是针对特定元素设置。另外课件里可能有公式图片这些图片需要保持原始比例不能被拉伸。可以在图片自适应脚本里加一个判断如果图片的class包含formula就跳过宽度调整。7.4 本地 HTML 与远程 HTML 的差异处理本地 HTML 加载速度快但资源路径需要特别注意。如果 HTML 里引用了本地图片baseURL必须指向正确的目录。远程 HTML 则要考虑网络超时和缓存策略。我通常会给远程请求设置 15 秒超时并在加载失败时显示一个友好的错误页面。let request URLRequest(url: url, cachePolicy: .returnCacheDataElseLoad, timeoutInterval: 15)cachePolicy设为.returnCacheDataElseLoad可以优先使用缓存减少流量消耗同时保证有网时能更新内容。8. 最后的经验分享这套方案我在多个项目里反复用过从 iOS 10 到 iOS 17 都跑过整体稳定性没问题。但有几个细节是我踩过坑之后才总结出来的这里再强调一下。第一viewport 脚本一定要在.atDocumentStart注入。我试过在.atDocumentEnd注入结果页面先按 980px 渲染了一遍然后才缩放到屏幕宽度用户能看到明显的闪烁。这个体验非常糟糕一定要避免。第二图片自适应的 JavaScript 要处理naturalWidth为 0 的情况。有些图片是懒加载的初始状态下naturalWidth是 0直接判断会跳过宽度调整。解决方案是监听load事件或者在setTimeout里延迟执行。第三禁用长按不要一刀切。全局禁用-webkit-user-select会导致输入框无法输入这个坑我踩过。正确的做法是只对图片和链接禁用呼出菜单文本区域保持可选。第四视频的playsinline属性在 iOS 10 以下不生效。如果你的 App 还要兼容 iOS 9视频只能全屏播放没有其他办法。这时候可以考虑用原生播放器替代 WebView 内的视频。第五测试的时候一定要用真机。模拟器上的 WKWebView 行为和真机有差异尤其是视频播放和长按事件。我遇到过模拟器上正常、真机上长按菜单依然弹出的情况最后发现是模拟器没有 3D Touch 硬件导致的。这套代码你可以直接复制到项目里用但建议根据自己的业务场景做调整。比如如果你的页面不需要视频就可以去掉视频自适应脚本减少不必要的性能开销。如果页面里有大量图片可以考虑用IntersectionObserver做懒加载进一步提升滚动流畅度。