Ubuntu 24.04下QtCharts QML模块加载失败问题求助

问题场景 #

尝试在QML中渲染QtCharts示例代码：

import QtCharts

...

        ChartView {
            title: "Line Chart"
            anchors.fill: parent
            antialiasing: true

            LineSeries {
                name: "Line"
                XYPoint {
                    x: 0
                    y: 0
                }
                ...
            }
        }

环境为Ubuntu 24.04，通过apt安装组件，系统已存在QtCharts相关库文件：

/usr/lib/x86_64-linux-gnu/libQt6ChartsQml.so.6
/usr/lib/x86_64-linux-gnu/libQt6Charts.so.6.4.2
/usr/lib/x86_64-linux-gnu/libQt6ChartsQml.so.6.4.2
/usr/lib/x86_64-linux-gnu/libQt6ChartsQml.so
/usr/lib/x86_64-linux-gnu/libQt6Charts.so

但运行C++/QML应用或直接执行QML代码时，出现如下错误：

$ qml qml/HardwareTestScreen.qml
QQmlApplicationEngine failed to load component
file:///home/guido/codes/application/qml/HardwareTestScreen.qml:1:1: module "QtCharts" is not installed
qml: Did not load any objects, exiting.

注：同一机器上基于QtWidgets的QtCharts应用可正常编译运行。

解决方案 #

1. 安装QML模块元数据包 #

QtCharts的QML模块依赖对应的元数据文件（如qmldir），仅库文件无法让QML引擎识别模块。执行以下命令检查是否已安装QML模块包：

dpkg -l | grep qt6-charts-qml

若无输出，说明缺少该包，执行安装：

sudo apt install qt6-charts-qml

2. 指定QML模块路径（安装后仍报错时） #

若已安装包但模块仍无法被找到，可通过环境变量指定QML引擎的模块搜索路径：

export QML2_IMPORT_PATH=/usr/lib/x86_64-linux-gnu/qt6/qml/QtCharts:$QML2_IMPORT_PATH

设置完成后重新运行QML文件：

qml qml/HardwareTestScreen.qml

3. C++/QML混合应用中注册模块 #

对于C++驱动的QML应用，需在代码中显式注册QtCharts模块，并在构建配置中链接对应组件：

代码层面（main.cpp）

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QtCharts>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    // 注册QtCharts模块，版本号匹配系统安装的Qt版本（如6.4）
    qmlRegisterModule("QtCharts", 6, 4);

    QQmlApplicationEngine engine;
    const QUrl url(u"qrc:/main.qml"_qs);
    QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
                     &app, [url](QObject *obj, const QUrl &objUrl) {
        if (!obj && url == objUrl)
            QCoreApplication::exit(-1);
    }, Qt::QueuedConnection);
    engine.load(url);

    return app.exec();
}

构建配置（CMakeLists.txt）

find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Charts)

target_link_libraries(your_app_name PRIVATE
    Qt6::Core
    Qt6::Gui
    Qt6::Qml
    Qt6::Charts
)

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