React Native Expo iOS应用TestFlight中出现白屏问题求助

核心问题分析 #

应用在Expo本地环境正常，但生产构建（开发构建/TestFlight）后WebView空白，能缩放说明WebView容器已加载，但内部HTML内容未正确渲染，大概率是生产环境下资源加载、权限配置或JavaScript注入时机问题。

排查与修复步骤 #

1. 修正本地HTML资源加载方式 #

使用require('./assets/body.html')加载本地HTML在生产构建中可能出现路径错误，改用expo-file-system读取文件内容确保路径正确：

import React, { useRef, useEffect, useState } from 'react';
// ...其他导入保持不变

export default function App() {
    const webViewRef = useRef(null);
    const [htmlContent, setHtmlContent] = useState(null);

    useEffect(() => {
        const loadHtml = async () => {
            try {
                const htmlPath = require('./assets/body.html').uri;
                const content = await FileSystem.readAsStringAsync(htmlPath);
                setHtmlContent(content);
            } catch (error) {
                console.error('加载HTML失败:', error);
            }
        };
        loadHtml();
    }, []);

    // HTML未加载完成时显示空容器
    if (!htmlContent) return <View style={styles.container} />;

    // ...其他逻辑保持不变

    // WebView的source改为动态加载的HTML内容
    return (
        <View style={styles.container}>
            <StatusBar hidden />
            <WebView
                ref={webViewRef}
                style={styles.webView}
                originWhiteList={['*']}
                source={{ html: htmlContent }}
                injectedJavaScriptBeforeContentLoaded={injectedJavaScript}
                onMessage={handleMessage}
                javaScriptEnabled={true}
                domStorageEnabled={true}
                allowFileAccess={true}
                allowUniversalAccessFromFileURLs={true}
            />
        </View>
    );
}

2. 调整JavaScript注入时机 #

生产环境下injectedJavaScript可能在WebView初始化前执行，导致脚本无法正确挂载，改用injectedJavaScriptBeforeContentLoaded确保脚本在HTML加载前注入：

<WebView
    // ...其他属性
    injectedJavaScriptBeforeContentLoaded={injectedJavaScript}
/>

3. 补充iOS权限隐私描述 #

TestFlight版本必须在app.json中添加权限描述，否则权限请求失败会阻塞WebView逻辑：

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSPhotoLibraryAddUsageDescription": "需要访问相册以保存调色板图片",
        "NSPhotoLibraryUsageDescription": "需要访问相册以保存调色板图片"
      }
    }
  }
}

4. 添加生产环境日志收集 #

无法访问TestFlight控制台时，将日志写入本地文件方便排查：

const logToFile = async (message) => {
    const logPath = `${FileSystem.documentDirectory}app_logs.txt`;
    const timestamp = new Date().toISOString();
    await FileSystem.appendAsStringAsync(logPath, `[${timestamp}] ${message}\n`);
};

// 在handleMessage的log/error分支调用
case 'log':
    const logMsg = `WebView日志: ${message.message}`;
    console.log(logMsg);
    await logToFile(logMsg);
    break;

case 'error':
    const errorMsg = `WebView错误: ${message.message}`;
    console.error(errorMsg);
    await logToFile(errorMsg);
    break;

5. 清理构建缓存后重新构建 #

构建缓存可能导致资源未更新，执行以下命令清理后重新构建：

npx expo prebuild --clean
eas build --platform ios --clear-cache

验证步骤 #

1. 先执行eas build --platform ios --profile development生成开发构建，安装到设备测试是否复现问题
2. 若开发构建正常，再提交TestFlight版本验证权限和资源加载逻辑

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