React+Vite项目用Cordova打包iOS白屏问题求助

问题背景 #

基于React+Vite开发的项目，使用Cordova打包部署移动端时，Android端运行正常，但iOS端出现白屏无法加载。

已尝试方案 #

• 遵循标准Cordova流程：创建项目、添加Android和iOS平台、将Vite构建产物移至www文件夹，执行cordova run ios命令。
• 在相同Cordova环境下测试Create React App（CRA）项目，iOS端可正常运行。
• 将项目构建文件替换为基础JavaScript文件，iOS端能正常加载。
• 修改HTML将基础JS以type="module"方式加载（Vite默认设置），加载失败。
• 尝试修改Vite构建配置生成非模块JS文件，问题未解决。

观察结果 #

• iOS端Cordova加载type="module"类型文件存在兼容性问题。
• 切换为SystemJS构建后，问题仍未解决。

临时方案 #

改用Capacitor替代Cordova可正常运行，但希望找到Cordova适配方案。

核心疑问 #

是否有人成功集成React、Vite与Cordova并完成iOS部署？求解决iOS端Cordova模块加载问题的思路或建议。

解决思路与建议 #

1. 调整Vite构建配置，生成兼容Cordova iOS的产物 #

Vite默认的type="module"在iOS Cordova的WebView中存在加载限制，可通过以下配置修改：

• 修改vite.config.js，设置构建格式为iife（立即执行函数），关闭模块相关特性：

export default defineConfig({
  build: {
    format: 'iife',
    modulePreload: {
      polyfill: false
    },
    rollupOptions: {
      output: {
        format: 'iife',
        name: 'MyReactApp' // 定义全局变量名，避免冲突
      }
    }
  }
})

• 构建后检查index.html，确保引入的JS文件没有type="module"属性，若存在可手动移除，或通过Vite的transformIndexHtml钩子自动处理。

2. 配置Cordova iOS的WebView参数 #

iOS Cordova的WebView默认可能限制ES模块加载，修改config.xml添加以下配置：

<platform name="ios">
  <preference name="AllowFileAccessFromFileURLs" value="true" />
  <preference name="AllowUniversalAccessFromFileURLs" value="true" />
  <preference name="UseWKWebView" value="true" /> <!-- 强制使用WKWebView，替代老旧的UIWebView -->
</platform>

WKWebView对现代JS特性支持更好，但需注意file://协议下的路径解析问题，确保静态资源引用为相对路径。

3. 修正Vite基础路径配置 #

Vite默认的绝对路径配置会导致iOS端路径解析错误，需设置为相对路径：

export default defineConfig({
  base: './', // 适配Cordova的file://协议访问
})

构建后确认所有JS、CSS、图片等静态资源的引用路径均为相对路径，无绝对路径前缀。

4. 调试iOS端WebView错误信息 #

通过Safari开发者工具定位具体报错：

• 打开Safari，进入「开发」菜单，选择连接的iOS设备，打开Cordova应用的WebView实例。
• 查看控制台的报错详情（如路径错误、权限限制、模块加载失败原因），针对性修复问题。

5. 安装Cordova WebView优化插件 #

使用cordova-plugin-ionic-webview优化WebView兼容性：

cordova plugin add cordova-plugin-ionic-webview

安装后重新构建并运行iOS项目，验证模块加载问题是否解决。

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