Qt 工程配置 .pro 文件变量详解

Qt 的 .pro（Project）文件是 qmake 构建系统的核心配置文件，用于定义如何编译和链接你的 Qt 项目。虽然 .pro 支持大量变量，但日常开发中只需掌握少数核心变量即可高效工作。
这些变量本质是告诉 qmake「如何编译项目」（比如编译成库还是程序、用哪些源码、链接哪些库、输出到哪），这里主要汇总一些主要的变量，于此备录！

核心配置变量

四大基础变量

TEMPLATE 项目类型 app（可执行程序）、lib（库）、subdirs（多子项目）

TARGET 输出文件名 TARGET = MyApp → 生成 MyApp.exe（Windows）或 MyApp（Linux/macOS）

QT 启用 Qt 模块 QT += core widgets network（Qt6 需显式加 widgets）

CONFIG 编译配置 CONFIG += c++17 console debug_and_release

💡 默认：TEMPLATE = app，QT = core gui（Qt5）或 core（Qt6）

`TEMPLATE`	项目类型	`app`（可执行程序）、`lib`（库）、`subdirs`（多子项目）
`TARGET`	输出文件名	`TARGET = MyApp` → 生成 `MyApp.exe`（Windows）或 `MyApp`（`Linux/macOS`）
`QT`	启用 Qt 模块	`QT += core widgets network`（`Qt6` 需显式加 `widgets`）
`CONFIG`	编译配置	`CONFIG += c++17 console debug_and_release`

资源管理

SOURCES C++ 源文件（.cpp）

HEADERS 头文件（.h）——主要用于 IDE 识别

FORMS Qt Designer 界面文件（.ui）

RESOURCES 资源文件（.qrc），如图标、翻译

TRANSLATIONS 翻译文件（.ts），用于多语言支持

`SOURCES`	C++ 源文件（`.cpp`）
`HEADERS`	头文件（`.h`）——主要用于 IDE 识别
`FORMS`	Qt Designer 界面文件（`.ui`）
`RESOURCES`	资源文件（`.qrc`），如图标、翻译
`TRANSLATIONS`	翻译文件（`.ts`），用于多语言支持

SOURCES += main.cpp mainwindow.cpp

HEADERS += mainwindow.h

FORMS += mainwindow.ui

RESOURCES += app.qrc

编译链接控制

DEFINES 预处理器宏 DEFINES += USE_FEATURE_X VERSION=1.0

INCLUDEPATH 头文件搜索路径 INCLUDEPATH += /usr/local/include/mylib

LIBS 链接外部库 LIBS += -L/path/to/lib -lmylib 或 LIBS += C:/lib/mylib.lib（Windows）

DESTDIR 可执行文件输出目录 DESTDIR = bin

⚠️ LIBS 中路径和库名顺序很重要：被依赖的库放后面。

`DEFINES`	预处理器宏	`DEFINES += USE_FEATURE_X VERSION=1.0`
`INCLUDEPATH`	头文件搜索路径	`INCLUDEPATH += /usr/local/include/mylib`
`LIBS`	链接外部库	`LIBS += -L/path/to/lib -lmylib` 或 `LIBS += C:/lib/mylib.lib`（Windows）
`DESTDIR`	可执行文件输出目录	`DESTDIR = bin`

构建配置

CONFIG += c++17 使用 C++17 标准（Qt5.7+ / Qt6）

CONFIG += console Windows 下显示控制台窗口（否则无黑窗）

CONFIG += warn_on 启用更多编译警告

CONFIG += debug_and_release 同时生成 Debug 和 Release 版本

CONFIG += c++17 console warn_on

`CONFIG += c++17`	使用 C++17 标准（Qt5.7+ / Qt6）
`CONFIG += console`	Windows 下显示控制台窗口（否则无黑窗）
`CONFIG += warn_on`	启用更多编译警告
`CONFIG += debug_and_release`	同时生成 Debug 和 Release 版本

平台判断

Windows

win32 {

LIBS += xxx.lib

DEFINES += _WIN32_WINNT=0x0601

}

Linux（非 macOS）

unix:!macx {

LIBS += -lpthread

}

macOS

macx {

QMAKE_LFLAGS += -mmacosx-version-min=10.14

}

Debug 模式

debug {

DEFINES += DEBUG_LOG

}

中间文件目录

MOC_DIR = build/moc # moc 输出

RCC_DIR = build/rcc # qrc 输出

UI_DIR = build/ui # ui_*.h 输出

OBJECTS_DIR = build/obj # .o 文件

DESTDIR = bin # 最终可执行文件

进阶变量

构成输出与文件控制

所有中间文件放入 build 目录，不污染源码

BUILD_DIR = $$OUT_PWD/build

DESTDIR = $$BUILD_DIR/bin

OBJECTS_DIR = $$BUILD_DIR/obj

MOC_DIR = $$BUILD_DIR/moc

RCC_DIR = $$BUILD_DIR/rcc

UI_DIR = $$BUILD_DIR/ui

TARGET_EXT 自定义输出扩展名

# 生成 myplugin.qmltypes 而非 .exe/.dll

TEMPLATE = aux TARGET = myplugin

TARGET_EXT = .qmltypes

QMAKE_POST_LINK = echo "Generating

QML types..." > ${DESTDIR}/${TARGET}${TARGET_EXT}

库项目控制

控制 Unix 共享库的版本链：

TEMPLATE = lib

CONFIG += shared TARGET = mycore

VERSION = 3.2.1

SOVERSION = 3 # 生成 libmycore.so.3 → libmycore.so.3.2.1

自动将 .dll 复制到可执行程序目录，便于调试：(Windows专用)

win32 {

DLLDESTDIR = $$PWD/../app/bin

}

target.path + INSTALLS —— 支持 make install

target.path = /usr/local/lib

headers.path = /usr/local/include/mylib

headers.files = $$files($$PWD/*.h)

INSTALLS += target headers

插件开发变量

TEMPLATE = lib

CONFIG += plugin
#关键：标记为插件

QT += widgets

#指定插件类型（决定安装子目录）

PLUGIN_TYPE = imageformats

#或 designer, bearer, sqldrivers 等
#可选：自定义插件目录名

PLUGIN_NAME = myjpeg

qmake 会自动将输出放入：

Linux: plugins/imageformats/libmyjpeg.so

Windows: plugins\imageformats\myjpeg.dll

运行时路径控制（`RPATH/RUNPATH`）

Unix/Linux：嵌入相对 RPATH

unix {

#方法1：使用 $$ORIGIN（推荐）

QMAKE_LFLAGS += -Wl,-rpath,\'\$$ORIGIN/lib\'

#方法2：通过 QMAKE_RPATHDIR（qmake 自动转为 -rpath）

QMAKE_RPATHDIR += $$DESTDIR/lib

}

macOS: 使用 @executable_path

macx {

QMAKE_LFLAGS += -Wl,-rpath,@executable_path/../Frameworks

}

自定义构建步骤

QMAKE_PRE_LINK / QMAKE_POST_LINK

QMAKE_PRE_LINK = echo "Preparing to link..."

QMAKE_POST_LINK = macdeployqt $$TARGET.app -qmldir=$$PWD/qml

常用于 macOS/Windows 打包（macdeployqt, windeployqt）。

自定义目标（QMAKE_EXTRA_TARGETS）

copy_config.commands = $(COPY_FILE) $$PWD/app.conf $$DESTDIR

first.depends = $(first) copy_config

export(first.depends)

QMAKE_EXTRA_TARGETS += first copy_config

效果：每次构建都会复制 app.conf 到输出目录。

条件构建与平台检测

精确平台检测

#编译器级别判断

linux-g++ {

message("Building on Linux with GCC")

}

win32-msvc {

message("Building on Windows with MSVC")

}

#架构判断

contains(QT_ARCH, x86_64) {

DEFINES += ARCH_64

}

Qt版本判断

equals(QT_MAJOR_VERSION, 6) {

QT += quickwidgets

} else {

QT += quick

}

或：

greaterThan(QT_MAJOR_VERSION, 5): QT += core5compat

变量操作与函数

$$replace(var, from, to) 字符串替换 OBJ = $$replace(SOURCES, ".cpp", ".o")

$$find(var, regex) 正则过滤 CPP = $$find(SOURCES, "\\.cpp$")

$$unique(list) 去重 INC = $$unique(INCLUDEPATH)

$$system(cmd) 执行 shell 命令 GIT_VER = $$system(git describe --tags)

$$absolute_path(path) 转绝对路径 ABS = $$absolute_path(rel/path)

⚠️ $$system() 会降低跨平台性，慎用。

`$$replace(var, from, to)`	字符串替换	`OBJ = $$replace(SOURCES, ".cpp", ".o")`
`$$find(var, regex)`	正则过滤	`CPP = $$find(SOURCES, "\\.cpp$")`
`$$unique(list)`	去重	`INC = $$unique(INCLUDEPATH)`
`$$system(cmd)`	执行 shell 命令	`GIT_VER = $$system(git describe --tags)`
`$$absolute_path(path)`	转绝对路径	`ABS = $$absolute_path(rel/path)`

资源与翻译

动态加载资源（避免编译进二进制）

#不使用 RESOURCES，而是运行时加载

#在代码中：

QResource::registerResource("data.rcc");

DISTFILES += data.rcc
#确保打包分发

自动更新翻译文件

#在 .pro 中声明

TRANSLATIONS = zh_CN.ts en_US.ts

#命令行更新：

#lupdate myproject.pro

#lrelease myproject.pro

大型项目：子项目（subdirs）

项目依赖与构建顺序

TEMPLATE = subdirs

SUBDIRS = core gui app

#指定依赖（影响 make 顺序）

app.depends = core gui

#子项目使用非默认 .pro 文件名

tools.subdir = tools/src

tools.file = tools/src/build.pro

SUBDIRS += tools

全局配置继承

#top.pro 在顶层 .pro 中设置，子项目自动继承：

CONFIG += c++17 warn_on

DEFINES += COMPANY_BUILD=1

#子项目无需重复定义

`Qt6`专属配置

统一 C++ 标准（推荐方式）

QMAKE_CXXSTD = c++17 # 比 CONFIG += c++17 更可靠
使用附加模块（需单独安装)
QT += mqtt coap          # 来自 qtconnectivity
QT += quick3d            # 来自 qtquick3d
QT += httpserver         # 来自 qthttpserver
🔍 模块是否可用可通过 qtConfig(mqtt) 检测。

快速查询

场景关键变量/机制

库版本管理 VERSION, SOVERSION, DLLDESTDIR

插件开发 CONFIG += plugin, PLUGIN_TYPE

绿色部署 QMAKE_RPATHDIR, -rpath='$$ORIGIN/lib'

自定义步骤 QMAKE_POST_LINK, QMAKE_EXTRA_TARGETS

动态逻辑 $$replace(), $$system(), $$find()

子项目 <sub>.depends, <sub>.file

安装支持 target.path, INSTALLS

Qt6 QMAKE_CXXSTD, 附加模块

场景	关键变量/机制
库版本管理	`VERSION`, `SOVERSION`, `DLLDESTDIR`
插件开发	`CONFIG += plugin`, `PLUGIN_TYPE`
绿色部署	`QMAKE_RPATHDIR`, `-rpath='$$ORIGIN/lib'`
自定义步骤	`QMAKE_POST_LINK`, `QMAKE_EXTRA_TARGETS`
动态逻辑	`$$replace()`, `$$system()`, `$$find()`
子项目	`<sub>.depends`, `<sub>.file`
安装支持	`target.path`, `INSTALLS`
`Qt6`	`QMAKE_CXXSTD`, 附加模块

`$` 的两种核心用法（必懂）

$$变量名：最常用，直接引用变量值

双 $ 表示「取变量的实际值」，是 qmake 中引用变量的标准写法；

#引用内置变量 PWD（当前.pro文件所在目录）

INCLUDEPATH += $$PWD/include # 等价于：INCLUDEPATH += F:/peoject/ComDlg_ssh/include（假设PWD是这个路径）

$${变量名}：明确变量边界，避免歧义

$${} 是「带边界的变量引用」，当变量名和后面的字符连在一起时，用它明确变量的范围，防止 qmake 解析错误；

#正确写法：用 $${} 明确 VER 是变量

DESTDIR = $$PWD/bin_$${VER} # 等价于：F:/peoject/ComDlg_ssh/bin_1.0.0

.pro 文件中的 $ 是「变量引用符」，核心写法是 $$变量名（基础）和 $${变量名}（明确边界）

配置共享pri文件

配置文件

#common.pri

#共享的编译选项

CONFIG += c++11

DEFINES += MY_DEFINE

#共享的头文件路径

INCLUDEPATH += $$PWD/../common/include

#共享的库路径

LIBS += -L$$PWD/../common/lib -lcommon

#平台相关设置

win32 {

DEFINES += WIN32_PLATFORM

LIBS += -lole32 -luser32

} else:unix {

DEFINES += UNIX_PLATFORM

LIBS += -lpthread

}

#config.pri (变量继承)

MY_VAR = value1

#app.pro

include(config.pri)

#现在可以使用 MY_VAR

message("Value: $$MY_VAR") #输出: value1

在pro文件中使用

#包含共享配置

include(common.pri)

注意事项

使用相对路径 $$PWD 指向 .pri 文件所在目录

模块化配置 按功能分离不同 .pri 文件

命名规范 如 common.pri, platform.pri, version.pri

避免循环包含 不要让 .pri 文件互相包含

文档注释 在 .pri 中添加配置说明

作用域意识 了解变量在不同 .pro 间的可见性

使用相对路径	`$$PWD` 指向 `.pri` 文件所在目录
模块化配置	按功能分离不同 `.pri` 文件
命名规范	如 `common.pri`, `platform.pri`, `version.pri`
避免循环包含	不要让 `.pri` 文件互相包含
文档注释	在 `.pri` 中添加配置说明
作用域意识	了解变量在不同 `.pro` 间的可见性

pri 文件用于代码复用和配置共享

每个 .pro 文件独立解析包含的 .pri 文件

变量在包含它的 .pro 文件中生效，不影响其他项目

posted on 2026-01-13 11:40 大伊万莱拉阅读(10) 评论(0) 收藏举报

刷新页面返回顶部

bao156

公告

核心配置变量

四大基础变量

资源管理

编译链接控制

构建配置

平台判断

中间文件目录

进阶变量

构成输出与文件控制

库项目控制

插件开发变量

运行时路径控制（`RPATH/RUNPATH`）

自定义构建步骤

条件构建与平台检测

变量操作与函数

资源与翻译

大型项目：子项目（subdirs）

`Qt6`专属配置

快速查询

`$` 的两种核心用法（必懂）

配置共享pri文件

bao156

公告

核心配置变量

四大基础变量

资源管理

编译链接控制

构建配置

平台判断

中间文件目录

进阶变量

构成输出与文件控制

库项目控制

插件开发变量

运行时路径控制（RPATH/RUNPATH）

自定义构建步骤

条件构建与平台检测

变量操作与函数

资源与翻译

大型项目：子项目（subdirs）

Qt6专属配置

快速查询

$ 的两种核心用法（必懂）

配置共享pri文件

运行时路径控制（`RPATH/RUNPATH`）

`Qt6`专属配置

`$` 的两种核心用法（必懂）