Cordova iOS 3.6.3适配iOS17+遇history.replaceState()安全错误求解决方案

问题背景 #

iOS17+对file://协议下的history.replaceState()/history.pushState()操作新增严格限制，仅允许修改URL的query和fragment部分，而cordova-ios@3.6.3及配套的jQuery Mobile 1.5.0未适配该限制，触发SecurityError。

同版本下的有效解决方案 #

1. 正确禁用jQuery Mobile的pushState

之前设置$pushEnableState = false的方式错误，需在mobileinit事件中配置，且必须在jQuery Mobile加载前执行：

// 这段代码必须放在 jquery.js 之后，jquery-mobile.js 之前
$(document).on("mobileinit", function() {
  $.mobile.pushStateEnabled = false;
  $.mobile.hashListeningEnabled = false; // 可选：进一步禁用哈希监听相关操作，降低触发风险
});

该配置强制jQuery Mobile使用哈希路由替代HTML5 History API，从根源避免调用replaceState()。

2. 修改cordova-ios的WebView权限配置

在项目根目录的config.xml中，针对iOS平台添加WebView权限偏好，放宽file://协议下的操作限制：

<platform name="ios">
  <preference name="AllowFileAccessFromFileURLs" value="true" />
  <preference name="AllowUniversalAccessFromFileURLs" value="true" />
</platform>

cordova-ios@3.6.3基于UIWebView，这两个配置可部分缓解iOS17+的权限限制。

3. 全局拦截history方法（兜底方案）

若前两种方案无效，可在页面最开始全局覆盖history.replaceState()和history.pushState()，仅允许符合iOS17+规则的操作：

// 放在所有业务脚本之前加载
(function() {
  // 处理replaceState
  const originalReplaceState = history.replaceState;
  history.replaceState = function(state, title, url) {
    if (url) {
      const currentBaseUrl = window.location.href.split(/[?#]/)[0];
      const newBaseUrl = url.split(/[?#]/)[0];
      // 仅当基础路径相同时，执行原方法
      if (currentBaseUrl === newBaseUrl) {
        return originalReplaceState.call(history, state, title, url);
      } else {
        // 路径不同时，改为修改哈希值适配现有路由
        const hashMatch = url.match(/#(.*)/);
        if (hashMatch) {
          window.location.hash = hashMatch[1];
        }
        return;
      }
    }
    return originalReplaceState.call(history, state, title, url);
  };

  // 同理处理pushState
  const originalPushState = history.pushState;
  history.pushState = function(state, title, url) {
    if (url) {
      const currentBaseUrl = window.location.href.split(/[?#]/)[0];
      const newBaseUrl = url.split(/[?#]/)[0];
      if (currentBaseUrl === newBaseUrl) {
        return originalPushState.call(history, state, title, url);
      } else {
        const hashMatch = url.match(/#(.*)/);
        if (hashMatch) {
          window.location.hash = hashMatch[1];
        }
        return;
      }
    }
    return originalPushState.call(history, state, title, url);
  };
})();

该方案过滤违反iOS限制的历史操作，同时保留合法的query/fragment修改，兼容现有路由逻辑。

4. 修改jQuery Mobile源码（可选）

若上述方案仍无效，可直接修改jQuery Mobile的navigation.js模块：

• 找到调用history.replaceState()的代码块
• 添加判断：当当前协议为file://时，改用哈希更新URL，而非调用replaceState()

注意事项 #

• 所有修改需在iOS17+设备上充分测试，确保银行项目的路由跳转、页面状态保存等业务逻辑正常
• 由于cordova-ios@3.6.3版本较旧，后续需评估长期版本升级可行性，避免因系统限制引发更多兼容性问题

内容的提问来源于stack exchange，提问作者Anil