QXlsx 库在麒麟 Linux（Qt 5.15.2）下完整安装步骤（含问题排查 & 经验总结）

一、前置准备：环境检查与依赖安装

1. 安装基础编译工具

复制代码

# 更新系统包列表（解决"找不到command-not-found数据库"问题）
sudo apt update
# 安装编译核心依赖
sudo apt install -y build-essential cmake git

2. 定位 Qt 的 qmake 路径（关键，避免版本冲突）

复制代码

# 查找系统中Qt 5.15.2的qmake绝对路径
which qmake
# 若输出为空，手动指定Qt安装路径查找（以你的路径为例）
find /home/user/soft/ -name "qmake"
# 验证qmake版本（确保是5.15.2）
/home/user/soft/Qt-5.15.2/bin/qmake -v

经验：若 qmake 版本不对，需用完整路径执行（如/home/user/soft/Qt-5.15.2/bin/qmake），避免调用系统默认 Qt 版本。

二、下载完整 QXlsx 源码（避免文件缺失）

1. 清理无效源码（若之前下载过不完整包）

复制代码

# 备份旧源码（可选）
mv ~/install/QXlsx-master ~/install/QXlsx-master-old
# 创建安装目录
mkdir -p ~/install && cd ~/install

2. 下载稳定版源码（含完整.pro 和头文件）

复制代码

# 下载v1.4.4版本（实测适配Qt 5.15.2）
wget https://github.com/QtExcel/QXlsx/archive/refs/tags/v1.4.4.zip
unzip v1.4.4.zip
# 重命名为易识别的目录
mv QXlsx-1.4.4 QXlsx-master

3. 验证源码完整性

复制代码

cd ~/install/QXlsx-master/QXlsx
# 必须包含以下文件/目录，否则源码不完整
ls -l | grep -E "QXlsx.pro|header|source"

经验：若缺少QXlsx.pro或header/source目录，说明源码包错误，需重新下载。

三、编译 QXlsx（优先 qmake 方式，避开 CMake 坑）

1. 进入正确的源码目录

复制代码

cd ~/install/QXlsx-master/QXlsx

2. 用 Qt 5.15.2 的 qmake 生成 Makefile

复制代码

# 关键：使用Qt 5.15.2的qmake完整路径
/home/user/soft/Qt-5.15.2/bin/qmake QXlsx.pro

常见问题：出现 "private headers" 警告 → 正常现象，不影响编译，直接忽略。

3. 编译源码（多核加速）

复制代码

# -j后接CPU核心数（如-j4），加快编译速度
make -j$(nproc)

验证编译成功 ：终端输出无error，且能找到libQXlsx.a（静态库）：

复制代码

find . -name "libQXlsx.a"  # 输出：./libQXlsx.a

经验：若编译报错 "找不到 Qt 头文件"，检查 qmake 路径是否正确，确保是 Qt 5.15.2 的 qmake。

四、手动安装 QXlsx（解决 make install 无操作问题）

1. 安装静态库到系统目录

复制代码

# 复制编译好的静态库到/usr/local/lib（系统默认库目录）
sudo cp ~/install/QXlsx-master/QXlsx/libQXlsx.a /usr/local/lib/
# 验证安装
ls /usr/local/lib/libQXlsx.a  # 输出路径即成功

2. 安装头文件到系统目录

复制代码

# 创建头文件目录
sudo mkdir -p /usr/local/include/QXlsx
# 复制所有头文件（含小写的xlsxdocument.h）
sudo cp ~/install/QXlsx-master/QXlsx/header/*.h /usr/local/include/QXlsx/
# 验证核心头文件
ls /usr/local/include/QXlsx/xlsxdocument.h  # 输出路径即成功

3. 更新系统库缓存

复制代码

sudo ldconfig

经验：若不执行ldconfig，Qt 项目可能提示 "找不到 libQXlsx.a"。

五、Qt 项目中验证 QXlsx 使用

1. 新建 Qt 控制台项目（Qt Creator）

项目类型：Qt Console Application
构建系统：qmake
Qt 版本：Qt 5.15.2
C++ 标准：C++11

2. 修改.pro 文件（核心配置）

复制代码

QT += core gui widgets
CONFIG += c++11 console
CONFIG -= app_bundle

# 链接QXlsx静态库（必须指定完整路径）
LIBS += /usr/local/lib/libQXlsx.a
# 引入头文件目录
INCLUDEPATH += /usr/local/include/QXlsx

SOURCES += main.cpp

3. 编写测试代码（main.cpp）

复制代码

#include <QCoreApplication>
#include "xlsxdocument.h"  // 注意：头文件是小写，Linux区分大小写
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    // 创建Excel文档
    QXlsx::Document xlsx;
    // 写入内容
    xlsx.write("A1", "QXlsx安装成功！");
    xlsx.write("B2", 2025);
    xlsx.write("C3", "麒麟Linux测试");

    // 保存文件
    bool isSaved = xlsx.saveAs("QXlsx_Test.xlsx");
    if (isSaved) {
        qDebug() << "✅ Excel文件生成成功，路径：" << a.applicationDirPath() + "/QXlsx_Test.xlsx";
    } else {
        qDebug() << "❌ Excel文件生成失败！";
    }

    return a.exec();
}

4. 编译运行

点击 Qt Creator 的 "构建并运行" 按钮（绿色三角）；
若控制台输出 "Excel 文件生成成功"，且在项目目录找到QXlsx_Test.xlsx，说明安装完全成功。

六、常见问题 & 解决经验

问题现象	核心原因	解决方法
`cmake..：未找到命令`	cmake 命令与参数间无空格，或未装 cmake	1. 安装 cmake：`sudo apt install cmake`；2. 修正命令：`cmake ..`（加空格）
找不到`CMakeLists.txt`	QXlsx 源码目录错误，或源码不完整	1. 进入`~/install/QXlsx-master/QXlsx`目录；2. 重新下载 v1.4.4 源码
`make install`提示 "无需做任何事"	QXlsx.pro 缺少 install 规则	手动复制`libQXlsx.a`和头文件到系统目录（见第四步）
找不到`XlsxDocument.h`	Linux 区分大小写，头文件是小写	代码中引用`#include "xlsxdocument.h"`（小写）
编译报错 "Qt 私有头文件"	QXlsx 使用 Qt 内部接口	忽略警告，或在.pro 中加`DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0x050F00`
链接报错 "undefined reference to QXlsx::XXX"	未链接静态库，或库路径错误	.pro 中指定完整库路径：`LIBS += /usr/local/lib/libQXlsx.a`

七、关键经验总结

路径是核心 ：麒麟 Linux 下 Qt 手动安装的 qmake 路径（/home/user/soft/Qt-5.15.2/bin/qmake）必须全程使用，避免版本冲突；
源码要完整：务必下载 v1.4.4 稳定版，避免新版源码缺失.pro 文件；
静态库安装要点 ：复制libQXlsx.a到/usr/local/lib、头文件到/usr/local/include/QXlsx，并执行ldconfig；
大小写敏感 ：Linux 下头文件xlsxdocument.h是小写，代码中引用需匹配，否则找不到头文件。