Cordova混合开发实战中遇到的常见问题与解决方案

又踩坑了，touchmove滚动失效

今天上线前测 iOS 版，发现列表页死活不滚动——手指按住拖动，页面纹丝不动。安卓一切正常，iOS 上连个 scroll 事件都不触发。我第一反应是：又来了，Cordova 的老朋友，iOS WebView 的 touch 滚动拦截问题。

不是第一次见，但每次修都像重新学一遍。这次我决定不靠“网上搜到的三行 CSS”糊弄过去，得摸清楚它到底在卡哪。先说结论：核心就两件事——阻止默认行为的时机不对，和iOS WebView 对 passive event listener 的严格限制。下面是我折腾了将近一天的真实路径。

试过三种方案，前两种全挂了

一开始我照着老经验，在 JS 里给容器加了 touchstart + touchmove 并调用 e.preventDefault()：

document.querySelector('.scroll-container').addEventListener('touchmove', function(e) {
  e.preventDefault(); // ❌ 这里直接报错：Unable to preventDefault inside passive event listener
});

控制台直接红字警告，而且滚动还是卡死。后来查了下，iOS WKWebView（Cordova 默认用的就是它）从 iOS 10+ 开始，把所有 touch 事件监听器默认设为 passive: true，也就是「你不能在事件处理函数里调用 preventDefault」——否则就给你报错并忽略掉。

那好，我改成显式声明 passive: false：

document.querySelector('.scroll-container').addEventListener('touchmove', function(e) {
  e.preventDefault();
}, { passive: false });

结果……安卓能滚了，iOS 还是不动。为啥？因为 Cordova 的 WebView 在初始化时已经给整个 document 绑了一堆全局 touch 监听器（比如用于手势识别、长按菜单啥的），它们全是 passive 的，而且优先级更高。你后加的监听器虽然设了 passive: false，但只要上面某一层父元素已经调用了 preventDefault 或触发了滚动锁定，你的容器就彻底没机会响应了。

我又去试了 CSS 方案：-webkit-overflow-scrolling: touch。加了，没用。再加 overscroll-behavior-y: contain，还是没用。最后翻 Cordova 官方 issue，发现有人提过：这个 bug 其实和 UIWebView 已废弃无关，而是 WKWebView 对 body 或 html 元素上设置了 height: 100% 或 overflow: hidden 的连锁反应。

我检查了自己的 index.html —— 果然，为了做全屏适配，我在 body 上写了：

body {
  height: 100%;
  overflow: hidden;
}

这里我踩了个坑：Cordova 的 iOS WebView 默认会把 body 当作滚动根节点，一旦你锁死了它的 overflow，它就真不滚了，不管你容器里嵌了多少层 overflow-y: auto。而安卓 WebView 更宽容，会自动 fallback 到子元素滚动。

最终解法：三步走，一行 CSS + 一点 JS + 一个配置

解决方法其实不复杂，但必须三者配合。我最后改完，iOS 滚动丝滑，安卓也没副作用，就是有个小问题：快速甩动时惯性略短（后面说原因）。

第一步：放开 body 的 overflow 锁定

删掉或注释掉所有对 body 和 html 的 overflow: hidden 或 height: 100% 约束。改成：

html, body {
  height: auto;
  min-height: 100%;
  margin: 0;
  padding: 0;
}

第二步：给滚动容器加明确的可滚动样式

别只写 overflow-y: auto，要带上 -webkit-overflow-scrolling: touch（iOS 专用加速滚动）和 overscroll-behavior-y: contain（防透传）：

.scroll-container {
  height: 500px; /* 必须有固定高度或 max-height */
  overflow-y: auto;
  -webkit-overflow-scrolling: touch;
  overscroll-behavior-y: contain;
}

第三步：用 JS 主动接管 touchmove 的 preventDefault，但只针对需要滚动的容器

重点来了：不是监听所有 touchmove，而是只在用户手指真正落在滚动区域上时，才临时把该容器的 touchmove 设为非 passive，并阻止默认行为——且仅阻止一次（避免重复调用报错）。我写了个轻量工具函数：

function enableScrollOnTouch(container) {
  let isScrolling = false;

  const handleTouchStart = () => {
    isScrolling = true;
  };

  const handleTouchMove = (e) => {
    if (!isScrolling) return;
    // 只在首次 move 时 preventDefault，后续不再调用
    if (e.cancelable && !e.defaultPrevented) {
      e.preventDefault();
    }
  };

  const handleTouchEnd = () => {
    isScrolling = false;
  };

  container.addEventListener('touchstart', handleTouchStart, { passive: true });
  container.addEventListener('touchmove', handleTouchMove, { passive: false });
  container.addEventListener('touchend', handleTouchEnd);
  container.addEventListener('touchcancel', handleTouchEnd);
}

// 调用
const scrollEl = document.querySelector('.scroll-container');
if (scrollEl) {
  enableScrollOnTouch(scrollEl);
}

这里注意：我用了 { passive: true } 绑 touchstart，是为了兼容性；而 touchmove 显式设为 { passive: false }，确保能调用 preventDefault。同时加了个 isScrolling 标志位，避免多次 preventDefault 导致异常。

为什么还有个小问题？惯性滚动变短了

改完之后，iOS 上确实能滚动了，但快速甩动后惯性滚动距离明显比原来短。我后来试了下发现，这是因为 -webkit-overflow-scrolling: touch 在 iOS 15.4+ 之后被标记为 deprecated（虽然还没删），而且它和现代 CSS 滚动行为有点冲突。如果你项目支持 iOS 16+，可以试试用 scroll-behavior: smooth 配合原生滚动 API，但我这次没升级，就先忍了——毕竟能滚比滚得多重要。

另外补充一个 Cordova 相关的坑：如果你用了 cordova-plugin-statusbar，记得检查它的配置。我之前在 config.xml 里写了：

<preference name="StatusBarOverlaysWebView" value="true" />

这会导致状态栏区域覆盖 WebView，有时也会干扰 touch 坐标计算。改成 false 后，滚动响应更稳定。顺手也加了 viewport 设置：

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

注意：这里的 user-scalable=no 不影响内部容器滚动，只禁缩放，反而能减少误触。

踩坑提醒：这三点一定注意

• iOS WKWebView 的 passive: true 是默认行为，想 preventDefault 就必须显式写 { passive: false }，且只能在 touchmove 上设，touchstart 不需要
• body 或 html 上任何 overflow: hidden 都会让 iOS 滚动直接失效，这是最常被忽略的根因
• Cordova 插件如 cordova-plugin-ionic-webview 或自定义 WebView 配置，可能覆盖默认滚动策略，遇到诡异问题先查插件文档

以上是我踩坑后的总结，希望对你有帮助。如果你有更好的方案，比如用 IntersectionObserver + 自定义滚动条完全绕开 native scroll，欢迎评论区交流。这个技巧的拓展用法还有很多，后续会继续分享这类博客。