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 文件中生效，不影響其他項目

大伊萬萊拉博客

大伊萬萊拉博客

博客 / 詳情

Qt 工程配置 .pro 文件變量詳解

核心配置變量

四大基礎變量

資源管理

編譯鏈接控制

構建配置

平台判斷

中間文件目錄

進階變量

構成輸出與文件控制

庫項目控制

插件開發變量

運行時路徑控制（`RPATH/RUNPATH`）

自定義構建步驟

條件構建與平台檢測

變量操作與函數

資源與翻譯

大型項目：子項目（subdirs）

`Qt6`專屬配置

快速查詢

`$` 的兩種核心用法（必懂）

配置共享pri文件

發佈評論

Product

Company

Support

Company

博客 / 詳情

Qt 工程配置 .pro 文件變量詳解

核心配置變量

四大基礎變量

資源管理

編譯鏈接控制

構建配置

平台判斷

中間文件目錄

進階變量

構成輸出與文件控制

庫項目控制

插件開發變量

運行時路徑控制（RPATH/RUNPATH）

自定義構建步驟

條件構建與平台檢測

變量操作與函數

資源與翻譯

大型項目：子項目（subdirs）

Qt6專屬配置

快速查詢

$ 的兩種核心用法（必懂）

配置共享pri文件

發佈 評論

運行時路徑控制（`RPATH/RUNPATH`）

`Qt6`專屬配置

`$` 的兩種核心用法（必懂）

發佈評論