问题：如何解决uniapp打包iOS正式版白屏问题？

Question

在使用 UniApp 打包 iOS 正式版时，部分开发者遇到应用启动后出现**白屏问题**，而调试版运行正常。此问题通常与**资源加载路径、H5运行环境或原生配置缺失**有关。常见原因包括：未正确配置`manifest.json`中的模块权限、未启用原生渲染器、未处理HTTPS请求、或未正确引入uni-app运行所需的基础库。此外，iOS对本地资源路径敏感，若使用相对路径或非法协议加载页面，也可能导致白屏。解决方法包括：检查并启用原生渲染器、配置合法域名、确保资源路径正确、以及在`manifest.json`中正确配置模块权限和启动页面。通过日志调试和真机日志分析，可进一步定位问题根源。

Answer 1

一、问题现象与背景

在使用 UniApp 打包 iOS 正式版时，部分开发者遇到应用启动后出现白屏问题，而调试版运行正常。此问题通常与资源加载路径、H5运行环境或原生配置缺失有关。

二、常见原因分析

以下是一些常见的导致白屏问题的原因：

• manifest.json中未正确配置模块权限；
• 未启用原生渲染器；
• 未处理HTTPS请求或未配置合法域名；
• 未正确引入uni-app运行所需的基础库；
• iOS对本地资源路径敏感，使用相对路径或非法协议加载页面。

三、解决思路与方法

为了解决上述问题，开发者可以从以下几个方面入手：

1. 检查 manifest.json 配置

确保在manifest.json中正确配置了模块权限和启动页面。例如：

{
  "plus": {
    "distribute": {
      "ios": {
        "CFBundleURLTypes": [
          {
            "CFBundleTypeRole": "Editor",
            "CFBundleURLName": "uniapp",
            "CFBundleURLSchemes": ["your-scheme"]
          }
        ]
      }
    },
    "modules": {
      "webview": {}
    }
  }
}
    

2. 启用原生渲染器

在 UniApp 中，可以通过以下方式启用原生渲染器：

1. 打开 HBuilderX 或使用命令行工具；
2. 在项目设置中勾选“使用原生渲染器”选项；
3. 重新打包 iOS 正式版本。

3. 配置 HTTPS 合法域名

iOS 对 HTTPS 请求有严格的限制，必须配置合法域名。请确保：

• 所有请求都使用 HTTPS 协议；
• 在manifest.json的“源码视图”中配置了正确的域名白名单；
• 服务器证书有效。

4. 检查资源路径是否正确

iOS 对本地资源路径敏感，建议使用绝对路径或 uni-app 提供的资源引用方式。避免使用以下路径：

• ../assets/image.png（相对路径）；
• file:// 或其他非法协议；
• 直接使用本地文件系统路径。

5. 引入必要的基础库

确保项目中正确引入了 UniApp 的基础库，如uni.js、uni.css等。可通过以下方式验证：

// main.js
import Vue from 'vue'
import App from './App'
import * as uni from '@dcloudio/uni-app'

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
  mpType: App.mpType
})
app.$mount()
    

四、日志调试与真机分析

使用 Xcode 或 Apple Configurator 连接真机，查看控制台日志，定位具体错误信息。

工具	用途	操作方式
Xcode	查看真机控制台日志	连接设备 → Window → Devices and Simulators → 查看日志
uni.preprocessLog()	前端日志输出	在 App.vue 中加入日志输出逻辑

五、流程图分析

以下是 UniApp 打包 iOS 白屏问题的排查流程图：

graph TD
            A[启动应用] --> B{调试版是否正常?}
            B -- 是 --> C[检查manifest.json配置]
            C --> D[启用原生渲染器]
            D --> E[配置HTTPS域名]
            E --> F[验证资源路径]
            F --> G[检查基础库引用]
            G --> H[查看真机日志]
            H --> I[定位问题]
            B -- 否 --> J[排查通用问题]