Qt5.12.0 macOS环境下相对路径加载文件失效仅绝对路径可用

AI 小北

2026-8-26

运行环境

操作系统：macOS Catalina 10.15.6
Qt版本：5.12.0

问题表现

使用文件绝对路径可正常加载资源，传入./images这类相对路径时加载失败，QDir::entryList(QDir::Files)返回空列表，无法读取目录下的图片文件。
目标是通过相对路径实现文件加载，提升代码健壮性与可维护性。

已尝试操作

先后调用QDir::currentPath()、QApplication::applicationDirPath()、QCoreApplication::applicationDirPath()接口，返回值均为绝对路径，未解决问题。
已在Qt Creator的Projects配置页禁用Shadow build，重新执行qmake构建后问题复现。

项目结构与问题代码

目录结构：images文件夹存放于项目根目录bili_tedu_timer下，内部包含20张待加载图片。
现有加载函数实现：

// load photo cantainer
void TimerDialog::loadPhotos(const QString &path)
{
    qDebug() << "in func loadPhotos, path is: " << path;
//    in func loadPhotos, path is:  "./images"
//    QDir dir("");
    QDir dir(path);
    // trevase current directory
    QStringList fileList = dir.entryList(QDir::Files);
    qDebug() << "in func loadPhotos, fileList is: " << fileList;
//  in func loadPhotos, fileList is:  ()

    for (int i=0; i<fileList.size();i++) {
        QImage image(path+"/"+fileList.at(i));
        qDebug() << "fileList.at(i): " << fileList.at(i);
        m_vecPhotos << image;
    }
    QStringList folderList = dir.entryList(QDir::Dirs|
                                           QDir::NoDotAndDotDot);
    for (int i = 0; i < folderList.size(); ++i) {
        loadPhotos(path+"/"+folderList.at(i));
    }
}

原因与修复方案

核心问题：Qt中./开头的相对路径，解析基准是程序启动时的工作目录，和项目源码根目录、可执行文件所在目录没有必然绑定关系。即使禁用Shadow build，Qt Creator启动程序时默认配置的工作目录也不一定指向images文件夹所在位置，直接硬编码./images本质是依赖运行时环境的偶然匹配，稳定性极差。

按以下步骤修复即可：

先确认实际工作目录
在main函数最开头加一行日志打印，运行后直接看当前工作目录的真实值，就能明确./images实际指向的路径位置，绝大多数场景下这个路径下根本不存在images文件夹，因此遍历结果为空：
```
qDebug() << "Runtime working directory:" << QDir::currentPath();
```
放弃硬编码./相对路径，用固定基准路径拼接
根据使用场景选稳定的路径基准，用Qt接口拼接资源路径，从根源上避免工作目录变动导致的路径失效：
- 发布场景（images文件夹和程序安装包放一起）：用QCoreApplication::applicationDirPath()作为基准，这个接口返回可执行文件所在的绝对路径，和程序启动位置无关，值固定。注意macOS的app包内部结构为xxx.app/Contents/MacOS/，如果把images放在app包同级目录，需要向上跳转3级目录：
```
// 图片放在app包内部MacOS目录下的images文件夹时用这个
QString imageRoot = QCoreApplication::applicationDirPath() + "/images";
// 图片放在app包同级目录时用这个
// QString imageRoot = QCoreApplication::applicationDirPath() + "/../../../images";
```
- 开发阶段（直接读取源码目录下的images文件夹）：在pro项目配置文件中定义源码路径宏，编译期写入源码根目录的绝对路径，不用手动改路径就能直接读源码下的资源，发布时切换到上面的发布路径逻辑即可：
```
# 加到.pro配置文件末尾
DEFINES += SRCDIR=\\\"$$PWD/\\\"
```
  代码中调用方式：
```
QString imageRoot = QString(SRCDIR) + "images";
```

增加路径合法性校验
拼接完路径先做存在性判断，提前抛出错误日志，减少排查成本：

QDir imageDir(imageRoot);
if (!imageDir.exists()) {
    qDebug() << "Image directory missing, checked path:" << imageRoot;
    return;
}

特殊场景排查
如果路径拼接正确仍无法读取，先检查Qt项目配置中是否开启了App Sandbox，将文件读取权限设置为允许读取应用目录即可；另外注意文件名大小写匹配，macOS默认分区大小写不敏感，但发布到Linux等大小写敏感的平台时，文件名大小写不匹配会直接加载失败，代码中写的文件名要和实际文件完全一致。

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