Qt 资源与素材：qrc、CMake、前缀和别名

知识概念更新于 2026-10-03编辑本文

素材来源和程序资源是两件事

原来的“资源库”条目指向阿里巴巴矢量图标库 Iconfont。它是寻找图标的入口；图标是否允许用于当前产品、导出 PNG/SVG 还是字体、需要哪些署名，应按具体素材说明确认。下载图标之后，还需要决定如何打包进 Qt 程序。

Qt 资源系统把文件内容经 rcc 编译后加入程序或库，让代码通过 :/... 访问。它不依赖运行时工作目录，但资源内容通常只读；用户需要修改的配置、数据库或导出文件应放在可写文件路径。Qt 资源系统

源路径、前缀和别名

名称	本例值	含义
源文件路径	`assets/notice.txt`	构建时从项目读取哪个文件
资源前缀	`/notes`	运行时资源树的目录
文件别名	`about.txt`	文件在该资源树中的名字
C++ 访问路径	`:/notes/about.txt`	`QFile` 使用的资源路径

原记录中的 logo.png、splashscreen.png 同样遵守这些规则。PREFIX /images 配合直接位于项目目录的 logo.png，得到 :/images/logo.png；如果源路径还含 assets/，就要通过 BASE 或别名确定是否保留这层目录。qt_add_resources

两条构建路径，共用一份可运行检查

建立下面四个文件。测试用纯文本，让资源路径的正确性可以直接断言，不需要先寻找图片。

assets/notice.txt，使用 UTF-8 并保留末尾换行：

VitaLogos resources

resources.qrc：

<RCC>
    <qresource prefix="/notes">
        <file alias="about.txt">assets/notice.txt</file>
    </qresource>
</RCC>

main.cpp：

#include <QCoreApplication>
#include <QFile>
#include <QIODevice>
#include <cassert>
#include <iostream>

int main(int argc, char **argv) {
    QCoreApplication app(argc, argv);
    QFile embedded(QStringLiteral(":/notes/about.txt"));
    if (!embedded.open(QIODevice::ReadOnly)) {
        std::cerr << embedded.errorString().toStdString() << '\n';
        return 1;
    }
    const QByteArray bytes = embedded.readAll();
    assert(bytes == "VitaLogos resources\n" || bytes == "VitaLogos resources\r\n");
    assert(!QFile::exists(QStringLiteral(":/notes/assets/notice.txt")));
    std::cout << "resource alias and payload passed\n";
}

CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)
project(ResourcePaths LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Core)
add_executable(resource_paths main.cpp)
target_link_libraries(resource_paths PRIVATE Qt6::Core)
option(USE_QRC "Compile the qrc file with AUTORCC" OFF)
if(USE_QRC)
    set_property(TARGET resource_paths PROPERTY AUTORCC ON)
    target_sources(resource_paths PRIVATE resources.qrc)
else()
    set_source_files_properties(assets/notice.txt PROPERTIES
        QT_RESOURCE_ALIAS "about.txt")
    qt_add_resources(resource_paths text_assets
        PREFIX "/notes"
        BASE "assets"
        FILES assets/notice.txt)
endif()

默认分支把文件直接交给 Qt 6 的目标版 qt_add_resources，生成结果会链接到该目标；USE_QRC=ON 分支则由 CMake 的 AUTORCC 处理列入目标的 .qrc。二选一即可，无须对相同资源重复生成两遍。不同资源集合的资源名称需要保持唯一。

配置时选择已经装好的 Qt Kit；例如通过 CMAKE_PREFIX_PATH 指向对应 Qt 安装目录。分别使用 build-direct 和 build-qrc 两个构建目录，并在第二次配置传入 -DUSE_QRC=ON。两次程序都应读取同一个运行时路径。CMake 生成器、编译器和执行文件目录按所用 Kit 决定，多配置生成器还要选择 Debug/Release。

换成图标或背景图时检查什么

先确认源文件存在并已进入构建，再核对完整资源路径；加载后检查 QPixmap::isNull() 或相应 API 的错误结果。把路径写成 :/pics/images/background.jpg 并不会创建这项资源。SVG、图标字体等还涉及相应的加载/渲染支持，不能只改扩展名。

内嵌资源变更需要重新构建。若资源放进静态库，还需考虑链接器是否把资源目标保留下来，必要时按 Qt 文档使用 Q_INIT_RESOURCE；这与程序工作目录无关。需要独立更新的大型数据可另行考虑外部 .rcc 与 QResource::registerResource，不要默认为每份素材都适合编进可执行文件。

来源：原 Qt CMake 资源笔记保留的构建方式、CMake AUTORCC、Iconfont 素材入口。