Qt 5.15迁移至6.10后，Android平台Widget应用中QML WebView显示空白但页面已加载的问题排查

阿华AIGC实验室

2026-4-2

我之前在Qt跨版本迁移时也踩过WebView显示的坑，结合你的测试代码和场景，给你梳理几个核心排查方向和可落地的修复方案：

一、先纠正一个关键误区：QTWEBENGINE_DISABLE_SANDBOX对你的场景无效

你提到尝试设置了QTWEBENGINE_DISABLE_SANDBOX环境变量，但这个配置是给QtWebEngine模块（自带Chromium内核）用的，而你当前使用的是QtWebView模块（底层调用Android系统自带的WebView），所以这个设置完全起不到作用，不用再浪费精力在这上面啦。

二、核心排查&修复方案

1. 确认AndroidManifest的关键配置（必须做！）

Android系统WebView的正常显示依赖几个核心配置，检查你的AndroidManifest.xml：

必须添加INTERNET权限：加载HTTPS页面需要网络权限，在<manifest>标签下添加：
```
<uses-permission android:name="android.permission.INTERNET"/>
```
强制开启硬件加速：WebView完全依赖硬件加速渲染，没有的话大概率显示空白。在<application>或对应<activity>标签里添加：
```
android:hardwareAccelerated="true"
```
检查qtprovider_paths.xml配置：确保里面的路径正确指向Qt的资源目录，避免资源加载异常导致WebView初始化失败。

2. 调整QQuickWidget的渲染与布局设置

Qt6对QQuickWidget的渲染逻辑做了优化，可能和Qt5的兼容性有差异：

在MainWindow构造里给QQuickWidget和主窗口强制开启硬件加速：

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent)
{
    // 主窗口开启硬件加速
    setAttribute(Qt::WA_HardwareAccelerated);

    mp_widget_webview = new QQuickWidget(this);
    // QQuickWidget开启硬件加速
    mp_widget_webview->setAttribute(Qt::WA_HardwareAccelerated);
    // 禁用软件渲染 fallback
    mp_widget_webview->setAttribute(Qt::WA_NoSystemBackground, false);

    mp_widget_webview->setSource(QUrl("qrc:/test.qml"));
    mp_widget_webview->setResizeMode(QQuickWidget::SizeRootObjectToView);
    mp_widget_webview->show();
}

简化QML布局：你当前的QML里WebView同时设置了anchors.centerIn: parent和anchors.fill: parent，这属于冗余布局，可能导致Qt6的布局引擎计算异常。直接修改test.qml为：

import QtQuick 2.15
import QtWebView 1.1

// 直接用WebView作为根对象，去掉外层Item避免布局嵌套问题
WebView {
    id: webView
    url: "https://qt.io"

    onLoadingChanged: function(loadRequest) {
        if (loadRequest.errorString)
            console.error("Load error: " + loadRequest.errorString);
        else
            console.error("Load success: " + loadRequest.url);
    }
}

3. 检查Qt6 Android套件的完整性

有时候Qt6的Android套件安装不完整，会导致WebView模块的底层依赖缺失（比如系统WebView的JNI绑定库）：

打开Qt Maintenance Tool，确认Qt 6.10.x -> Android -> Qt WebView组件已安装；
清理Android构建目录，重新构建项目（避免旧的Qt5缓存文件干扰）。

4. 强制指定Qt Quick的渲染后端

Qt6默认会根据设备自动选择渲染后端，但部分Android设备可能 fallback到软件渲染，而WebView不支持软件渲染：

在main.cpp的最开头添加环境变量设置，强制使用OpenGL后端：

#include <QApplication>
#include <QtWebView>
#include "mainwindow.h"

int main(int argc, char *argv[])
{
    // 强制Qt Quick使用OpenGL渲染后端
    qputenv("QT_QUICK_BACKEND", "opengl");

    // QtWebView初始化必须在QApplication创建之前
    QtWebView::initialize();

    QApplication a(argc, argv);
    MainWindow w;
    w.show();
    return a.exec();
}

5. 替换QQuickWidget为纯QML工程验证

如果上面的方案都没用，可以先做一个最小验证：创建一个纯QML的Android工程（不用QMainWindow+QQuickWidget），直接在main.qml里放WebView，看是否能正常显示。如果纯QML正常，说明问题出在QQuickWidget和WebView的嵌套兼容上，此时可以考虑：