寫項(xiàng)目模板這事兒說(shuō)實(shí)話比寫業(yè)務(wù)代碼更容易翻車。業(yè)務(wù)代碼寫錯(cuò)了最多功能跑不通項(xiàng)目模板要是有問(wèn)題那真的是一傳十、十傳百整個(gè)團(tuán)隊(duì)、整個(gè)倉(cāng)庫(kù)的工程化地基都跟著歪。尤其是Qt的QML項(xiàng)目C和QML混著寫資源、翻譯、類型注冊(cè)、模塊導(dǎo)入、打包部署全攪在一起配置起來(lái)比純Widgets項(xiàng)目麻煩得多。我梳理了一份自用的Qt QML項(xiàng)目CMake模板整套思路從Qt 5.15一直用到Qt 6.7中間踩了不少坑今天把這套東西的來(lái)龍去脈、核心配置和實(shí)操過(guò)程攤開講清楚希望對(duì)正在折騰CMake的Qt開發(fā)者有幫助。1. 為什么QML項(xiàng)目需要一套CMake模板而不是繼續(xù)用qmake我先說(shuō)一個(gè)觀點(diǎn)如果你現(xiàn)在還在用qmake管新的QML項(xiàng)目后面十有八九要后悔。Qt官方在6.0之后已經(jīng)把CMake扶正成默認(rèn)構(gòu)建系統(tǒng)qmake雖然還在維護(hù)但新特性基本不再往上面疊。更關(guān)鍵的是QML模塊化、靜態(tài)編譯、Android/iOS交叉編譯、CI流水線里矩陣并行構(gòu)建這些需求CMake的處理能力比qmake強(qiáng)一個(gè)量級(jí)。那為什么專門強(qiáng)調(diào)“QML項(xiàng)目”而不是泛泛的Qt項(xiàng)目因?yàn)樵赒ML項(xiàng)目里構(gòu)建系統(tǒng)不止是“編譯C代碼”這么簡(jiǎn)單它還要解決幾件qmake時(shí)代很痛苦的事第一QML文件本身不算編譯單元但它有導(dǎo)入路徑、有模塊URI、有類型注冊(cè)信息。qmake時(shí)代你經(jīng)常要在.pro里手工維護(hù)QML_IMPORT_PATH和一些別扭的資源路徑稍不留神Main.qml里引一個(gè)自定義控件就報(bào)module not found。CMake的qt_add_qml_module把這一攤子事自動(dòng)收口了qml文件、C類型、資源前綴、qmldir文件全部聲明式管理省掉大量手工配置。第二QML項(xiàng)目幾乎必然要混編C不管是做核心算法、封裝第三方庫(kù)還是暴露一些Model給前端。CMake對(duì)C的生態(tài)支持顯然是碾壓級(jí)的——vcpkg、conan、FetchContent這些包管理工具都是優(yōu)先兼容CMake你一個(gè)Qt項(xiàng)目如果要引一個(gè)Hash庫(kù)、一個(gè)網(wǎng)絡(luò)庫(kù)用CMake會(huì)順滑很多。第三跨平臺(tái)部署。QML項(xiàng)目比Widgets項(xiàng)目更依賴插件和QML模塊的運(yùn)行時(shí)文件單靠手工拷貝根本不可能。這套模板里把windeployqt/macdeployqt/linuxdeployqt全部接進(jìn)CMake的POST_BUILD階段構(gòu)建完自動(dòng)打完包雙擊就能跑不存在“在自己機(jī)器上能跑換臺(tái)機(jī)器就白屏”的尷尬。還有一個(gè)很實(shí)際的原因團(tuán)隊(duì)協(xié)作。模板把所有人的構(gòu)建姿勢(shì)統(tǒng)一了新人拉下來(lái)代碼或者用CMakePresets跑一條命令環(huán)境就一樣了。不用每個(gè)人在本地手動(dòng)配qmake路徑、裝這裝那也不容易出現(xiàn)“在我這是好的”這種經(jīng)典甩鍋。所以這篇模板不是炫技是給有真實(shí)QML工程需求的開發(fā)者一個(gè)可以直接抄的基線。我自己在幾個(gè)真實(shí)項(xiàng)目里反復(fù)調(diào)整過(guò)它現(xiàn)在這套結(jié)構(gòu)在Windows上配MSVC和Ninja都能跑在Linux上配GCC也沒(méi)問(wèn)題放到macOS上一樣可以編出dmg包。下面我把它拆開講。2. 模板整體設(shè)計(jì)與目錄結(jié)構(gòu)拆解先看模板的整體結(jié)構(gòu)。我采用的是一個(gè)偏中型項(xiàng)目的組織方式既不是單文件堆到底也沒(méi)有過(guò)度抽象到每個(gè)QML頁(yè)面一個(gè)子模塊。目錄大概長(zhǎng)這樣MyQmlApp/ ├── CMakeLists.txt ├── CMakePresets.json ├── cmake/ │ ├── DeployMac.cmake │ ├── DeployLinux.cmake │ └── DeployWindows.cmake ├── src/ │ ├── main.cpp │ ├── AppEngine.h │ ├── AppEngine.cpp │ └── Models/ │ ├── TaskModel.h │ └── TaskModel.cpp ├── qml/ │ ├── Main.qml │ ├── pages/ │ │ ├── HomePage.qml │ │ └── SettingsPage.qml │ ├── components/ │ │ ├── AppButton.qml │ │ └── AppListView.qml │ └── assets/ │ ├── images/ │ │ └── logo.svg │ └── fonts/ ├── resources/ │ ├── translations/ │ │ ├── app_zh_CN.ts │ │ └── app_en_US.ts │ └── config/ │ └── app.ini └── tests/ └── tst_AppEngine/ ├── CMakeLists.txt └── tst_AppEngine.cpp2.1 為什么把源碼、QML、資源分開而不是全塞進(jìn)qrc有人習(xí)慣把所有QML文件一股腦塞進(jìn)qrc資源里然后用qrc:/路徑訪問(wèn)。這對(duì)小demo沒(méi)問(wèn)題項(xiàng)目一復(fù)雜就蛋疼——合并沖突頻繁、每次改QML都要重新編譯資源、無(wú)法在運(yùn)行時(shí)動(dòng)態(tài)加載插件或主題資源。所以我把qml/目錄當(dāng)成源碼目錄來(lái)處理通過(guò)CMake的qt_add_qml_module自動(dòng)把它們納入資源編譯真正常變的圖片、字體、配置文件放在resources/目錄里單獨(dú)管理可以按需決定打進(jìn)QRC還是走外部路徑。src/下只放C源文件qml/下只放QML相關(guān)文件。這種分離有一個(gè)額外好處CI里可以做很細(xì)粒度的緩存和增量編譯改一個(gè)QML文件不會(huì)觸發(fā)整個(gè)C文件樹的重編反過(guò)來(lái)改C時(shí)QML文件也不用全部重新處理。tests/目錄單獨(dú)拆出來(lái)是給后續(xù)接入CTest留的口子。純QML項(xiàng)目可能不太需要但一旦C模型邏輯變多單元測(cè)試基本是必需品。2.2 CMakeLists.txt主文件全貌與逐段說(shuō)明主CMakeLists.txt看起來(lái)是這樣的我直接貼一個(gè)可運(yùn)行版本cmake_minimum_required(VERSION 3.24) project(MyQmlApp VERSION 1.0.0 DESCRIPTION A CMake template for Qt Quick application LANGUAGES CXX ) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_EXPORT_COMPILE_COMMANDS ON) find_package(Qt6 6.5 REQUIRED COMPONENTS Quick Gui Widgets ) qt_standard_project_setup() qt_add_executable(MyQmlApp src/main.cpp src/AppEngine.h src/AppEngine.cpp src/Models/TaskModel.h src/Models/TaskModel.cpp ) qt_add_qml_module(MyQmlApp URI MyQmlApp VERSION 1.0 QML_FILES qml/Main.qml qml/pages/HomePage.qml qml/pages/SettingsPage.qml qml/components/AppButton.qml qml/components/AppListView.qml SOURCES src/AppEngine.h src/AppEngine.cpp src/Models/TaskModel.h src/Models/TaskModel.cpp RESOURCE_PREFIX /qt/qml OUTPUT_DIRECTORY qml/MyQmlApp ) target_compile_definitions(MyQmlApp PRIVATE $$CONFIG:Debug:QT_QML_DEBUG ) qt_finalize_executable(MyQmlApp) if(WIN32) include(cmake/DeployWindows.cmake) deploy_windows_qt(MyQmlApp) elseif(APPLE) include(cmake/DeployMac.cmake) deploy_mac_qt(MyQmlApp) else() include(cmake/DeployLinux.cmake) deploy_linux_qt(MyQmlApp) endif() enable_testing() add_subdirectory(tests)這里有幾個(gè)點(diǎn)我必須著重強(qiáng)調(diào)一下它們是我反復(fù)試錯(cuò)之后總結(jié)出來(lái)的關(guān)鍵第一CMAKE_AUTOMOC一定要開。QML模塊里的C類一般會(huì)帶Q_OBJECT宏如果不開AUTOMOC你會(huì)在鏈接階段遇到一堆“undefined reference to vtable for xxx”之類的玄學(xué)錯(cuò)誤。這個(gè)不要手工去逐個(gè)添加moc文件CMake的AUTOMOC能自動(dòng)處理。第二CMAKE_EXPORT_COMPILE_COMMANDS ON強(qiáng)烈建議開著。生成compile_commands.json之后不管有沒(méi)有Qt Creator你都能用clangd或者各種代碼補(bǔ)全工具拿到準(zhǔn)確的編譯參數(shù)否則QML的C側(cè)自動(dòng)補(bǔ)全經(jīng)常會(huì)抽風(fēng)。第三qt_standard_project_setup()是Qt 6.3往后才有的它統(tǒng)一設(shè)置了包括CMAKE_AUTOMOC在內(nèi)的一些Qt相關(guān)默認(rèn)值。不過(guò)我在模板里仍然顯式寫了AUTOMOC這些選項(xiàng)因?yàn)槔享?xiàng)目里可能有自定義的生成器或者子目錄覆寫了全局設(shè)置顯式寫出來(lái)更穩(wěn)。第四qt_add_executable和qt_add_qml_module都引用了同一個(gè)可執(zhí)行目標(biāo)MyQmlApp。這是Qt官方推薦的做法——先建可執(zhí)行目標(biāo)再用qt_add_qml_module給這個(gè)目標(biāo)掛上QML模塊配置。這樣QML和C最終打進(jìn)同一個(gè)可執(zhí)行文件里關(guān)鍵是在qt_add_executable里不用重復(fù)放QML文件那些文件只屬于qt_add_qml_module管理。第五qt_finalize_executable這個(gè)函數(shù)必須在所有和該目標(biāo)相關(guān)的配置完成后調(diào)用。尤其是你要打包部署、加翻譯文件、生成插件的時(shí)候順序不能亂。我之前有個(gè)項(xiàng)目因?yàn)榘阉崆傲藢?dǎo)致macOS上部署腳本拿不到info.plist折騰了小半天。2.3 CMakePresets.json一條命令統(tǒng)一所有環(huán)境CMakePresets是CMake 3.21之后引入的目的就是解決“不同人用不同參數(shù)配置CMake”的混亂。下面是我模板里的presets文件{ version: 6, cmakeMinimumRequired: { major: 3, minor: 24, patch: 0 }, configurePresets: [ { name: default, displayName: 默認(rèn)開發(fā)配置, generator: Ninja, binaryDir: ${sourceDir}/build/${presetName}, cacheVariables: { CMAKE_BUILD_TYPE: Debug, CMAKE_EXPORT_COMPILE_COMMANDS: ON } }, { name: release, displayName: 發(fā)布配置, generator: Ninja, binaryDir: ${sourceDir}/build/${presetName}, cacheVariables: { CMAKE_BUILD_TYPE: Release, CMAKE_EXPORT_COMPILE_COMMANDS: ON } }, { name: vs2022, displayName: Visual Studio 2022, generator: Visual Studio 17 2022, binaryDir: ${sourceDir}/build/${presetName}, cacheVariables: { CMAKE_PREFIX_PATH: C:/Qt/6.6.2/msvc2019_64 } } ], buildPresets: [ { name: default, configurePreset: default }, { name: release, configurePreset: release }, { name: vs2022-debug, configurePreset: vs2022, configuration: Debug }, { name: vs2022-release, configurePreset: vs2022, configuration: Release } ] }用Ninja做默認(rèn)生成器是因?yàn)樗赪indows上構(gòu)建速度快增量編譯體驗(yàn)比VS好得多。但有些團(tuán)隊(duì)依賴VS的調(diào)試器和性能分析器所以我保留了一個(gè)vs2022預(yù)設(shè)。注意VS是多配置生成器構(gòu)建時(shí)用--config指定Debug還是Release而Ninja是單配置構(gòu)建類型在配置階段就定死了必須分開預(yù)設(shè)。CMAKE_PREFIX_PATH是Qt開發(fā)里最容易踩坑的地方。很多人以為裝完Qt就能被find_package找到其實(shí)CMake并不知道你的Qt裝在哪。如果你不想每次配置都傳-DCMAKE_PREFIX_PATH...就把路徑寫進(jìn)preset里。Windows上務(wù)必分清msvc2019_64和mingw_64目錄Toolchain不一樣混用會(huì)編出各種奇怪錯(cuò)誤。3. QML模塊注冊(cè)、類型導(dǎo)出與資源編譯的核心細(xì)節(jié)這一節(jié)是最能體現(xiàn)QML項(xiàng)目模板特殊性的地方。很多人把CMake配上跑通就覺(jué)得完事了結(jié)果QML里import MyQmlApp 1.0就是找不到或者自定義類型在QML里顯示為不可見對(duì)象。這些問(wèn)題的根源幾乎都在于模塊注冊(cè)和類型導(dǎo)出沒(méi)有配齊。3.1 qt_add_qml_module這個(gè)函數(shù)到底干了什么qt_add_qml_module是Qt 6.x里面管理QML模塊的核心函數(shù)它做的事情非常多把QML_FILES列出來(lái)的QML文件收集起來(lái)作為QML模塊的內(nèi)容。把SOURCES里列出的C類型注冊(cè)到QML運(yùn)行時(shí)。自動(dòng)生成qmldir文件和模塊類型信息也就是QML Designer里能看到類型列表的那個(gè)基礎(chǔ)數(shù)據(jù)。管理虛擬目錄/資源前綴讓QML模塊在代碼里能夠通過(guò)qrc:///qt/qml這樣的路徑被訪問(wèn)。理解了這個(gè)函數(shù)很多問(wèn)題就迎刃而解了。比如你在QML里import MyQmlApp 1.0CMake會(huì)根據(jù)qt_add_qml_module里的URI MyQmlApp生成對(duì)應(yīng)的模塊目錄。如果URI和QML文件里的import語(yǔ)句對(duì)不上運(yùn)行時(shí)100%報(bào)module not found。這種錯(cuò)誤編譯器不會(huì)提示只有啟動(dòng)應(yīng)用時(shí)才炸。再比如SOURCES和QML_FILES的區(qū)別。QML_FILES只管純QML定義SOURCES是你用C實(shí)現(xiàn)并注冊(cè)給QML使用的類型。這兩種文件在Qt里會(huì)被QML編譯器以不同的方式處理不能混放。3.2 QML_ELEMENT與類型注冊(cè)的方式C類型要暴露給QML除了放在qt_add_qml_module的SOURCES之外類定義本身就帶有注冊(cè)標(biāo)記#pragma once #include QObject #include QQmlEngine class AppEngine : public QObject { Q_OBJECT QML_ELEMENT QML_SINGLETON public: explicit AppEngine(QObject *parent nullptr); Q_INVOKABLE QString greeting() const; };其中的QML_ELEMENT宏是關(guān)鍵。它告訴Qt的這個(gè)構(gòu)建系統(tǒng)“把我這個(gè)類導(dǎo)出到QML模塊里”。如果沒(méi)有這個(gè)宏即使你把.h/.cpp放在qt_add_qml_module的SOURCES里QML側(cè)也new不出來(lái)對(duì)應(yīng)對(duì)象。我在模板中把AppEngine和TaskModel都列為SOURCES并且用了QML_ELEMENT和QML_SINGLETON宏。QML_SINGLETON只在確實(shí)需要一個(gè)全局單例對(duì)象時(shí)才用——比如應(yīng)用配置、主題管理器——如果你的模型需要多個(gè)實(shí)例千萬(wàn)別打上這個(gè)宏。一個(gè)常見錯(cuò)誤是給普通的Model類加了QML_SINGLETON結(jié)果在QML里創(chuàng)建第二個(gè)實(shí)例時(shí)報(bào)錯(cuò)排查起來(lái)特別迷惑。還有一個(gè)細(xì)節(jié)qt_add_qml_module默認(rèn)生成的模塊類型屬于“static”模式也就是說(shuō)只有你顯式列在QML_FILES或SOURCES里的類型才會(huì)被注冊(cè)。這比qmake時(shí)代那種掃描整個(gè)目錄樹的“野路子”可靠很多不容易重復(fù)注冊(cè)也不會(huì)漏注冊(cè)。3.3 資源前綴、OUTPUT_DIRECTORY與QML路徑到底怎么對(duì)應(yīng)資源前綴是QML模塊比較繞的一個(gè)點(diǎn)我甚至覺(jué)得這是整個(gè)模板里最容易被誤解的配置。qt_add_qml_module默認(rèn)的RESOURCE_PREFIX是/qt/qml。所有模塊文件會(huì)以/qt/qml/URI/文件相對(duì)路徑的形式掛在Qt資源系統(tǒng)里。比如我們的URI是MyQmlAppMain.qml的完整資源路徑就是qrc:/qt/qml/MyQmlApp/Main.qml。這樣做的好處是各模塊之間不會(huì)撞路徑。OUTPUT_DIRECTORY qml/MyQmlApp這一段則控制編譯產(chǎn)物中QML模塊文件在構(gòu)建目錄里的存放位置。如果你不設(shè)置這個(gè)選項(xiàng)Qt默認(rèn)會(huì)放到構(gòu)建目錄下某個(gè)層級(jí)生成的目錄里。設(shè)置這個(gè)選項(xiàng)的主要原因是讓調(diào)試、查看編譯輸出的QML文件、以及后續(xù)部署腳本拿文件時(shí)路徑是可預(yù)期和穩(wěn)定的。關(guān)于資源路徑有個(gè)坑值得一提如果你在QML里用Loader動(dòng)態(tài)加載一個(gè)qml文件Loader的source如果寫成qrc:/qt/qml/MyQmlApp/pages/HomePage.qml那路徑必須和資源前綴嚴(yán)格一致。一旦改了RESOURCE_PREFIX所有手工寫的路徑都要跟著改。所以模板里盡量不要在QML代碼里硬編碼長(zhǎng)路徑最好用相對(duì)路徑配合Qt.resolvedUrl或者直接用qmldir里的模塊導(dǎo)出。3.4 圖片、字體、配置文件在哪里放真正的項(xiàng)目不可能沒(méi)有圖片圖標(biāo)字體。我經(jīng)驗(yàn)是小的、固定不變的資源logo、某些固定圖標(biāo)放qml/assets里并在QML_FILES里逐項(xiàng)聲明讓Qt的QML編譯器做優(yōu)化大體積的、可能會(huì)按需加載的資源比如多語(yǔ)言文檔、皮膚包放resources/下面通過(guò)普通QRC或者運(yùn)行時(shí)文件目錄加載。在qt_add_executable里是看不到這些QML資源文件的——它們歸qt_add_qml_module管。如果是純資源文件還有另一個(gè)函數(shù)qt_add_resources可以用它適合把亂七八糟的非QML資源打包成QRC。翻譯文件.ts/.qm則建議用qt_add_translations或者qt_add_lupdate來(lái)處理這樣可以集成到構(gòu)建流程里。我模板中的resources/translations目錄就專門放翻譯文件后續(xù)可以在CMake里用QT_TRANSLATIONS_DIR把它們帶上。當(dāng)然如果你的項(xiàng)目根本不做多語(yǔ)言這塊可以整個(gè)砍掉不用追求大而全。4. 構(gòu)建類型、輸出路徑與VS工程相對(duì)路徑寫法詳解這塊看起來(lái)是很基礎(chǔ)的CMake知識(shí)但實(shí)際項(xiàng)目里總有人反復(fù)踩坑尤其是從Windows/VS環(huán)境入門的Qt開發(fā)者。我在模板里特意把構(gòu)建配置設(shè)計(jì)得清晰一些目的就是減少這類“低級(jí)但致命”的問(wèn)題。4.1 Debug與Release的多配置管理CMake有兩種構(gòu)建方式理解這個(gè)你后面所有配置都會(huì)順單配置生成器Ninja、Unix Makefiles。這類生成器在cmake -S . -B build配置階段就必須定下構(gòu)建類型通過(guò)CMAKE_BUILD_TYPE指定。所以我在presets里為Ninja分別準(zhǔn)備了defaultDebug和release兩個(gè)configure preset。多配置生成器Visual Studio、Xcode。它們可以在同一個(gè)構(gòu)建目錄里同時(shí)生成Debug和Release兩套配置構(gòu)建時(shí)通過(guò)--config來(lái)選。Qt官方包在Windows上默認(rèn)提供了MSVC和MinGW兩種ABI的庫(kù)。用VS生成器時(shí)CMAKE_PREFIX_PATH必須指向msvc版本的Qt不能指向MinGW版本否則鏈接階段會(huì)因?yàn)锳BI不兼容報(bào)一堆無(wú)法解析的錯(cuò)誤。這個(gè)我吃了不少虧寫在這里提醒大家。target_compile_definitions里那行$$CONFIG:Debug:QT_QML_DEBUG也值得解釋下它的意思是當(dāng)配置為Debug時(shí)給目標(biāo)加一個(gè)QT_QML_DEBUG宏。這個(gè)宏會(huì)開啟QML運(yùn)行時(shí)的一系列調(diào)試信息輸出比如加載器日志、模型調(diào)試信息等。Release模式下不加避免性能損耗和信息泄露。4.2 讓輸出目錄不再套一層Debug/Release子目錄很多從VS工程轉(zhuǎn)過(guò)來(lái)的人都很煩CMake默認(rèn)把輸出文件放到build/Debug、build/Release這種子目錄里找exe還得先點(diǎn)兩層目錄。熱搜詞里就有“cmake輸出路徑去掉debug”這個(gè)痛點(diǎn)確實(shí)大。其實(shí)解決辦法非常直接顯式設(shè)置輸出目錄把配置名從路徑里去掉。在以Visual Studio為代表的多配置生成器下如果不做設(shè)置默認(rèn)輸出目錄會(huì)帶上$(Configuration)子目錄。為了讓所有配置的輸出都落在同一個(gè)目錄可以在頂層CMakeLists里統(tǒng)一指定if(MSVC) foreach(config Debug Release RelWithDebInfo MinSizeRel) string(TOUPPER ${config} config_upper) set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_${config_upper} ${CMAKE_BINARY_DIR}/bin) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY_${config_upper} ${CMAKE_BINARY_DIR}/bin) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY_${config_upper} ${CMAKE_BINARY_DIR}/lib) endforeach() else() set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) endif()這段代碼的思路對(duì)于多配置生成器逐個(gè)配置設(shè)置一次輸出目錄對(duì)于單配置生成器直接設(shè)置不帶配置名后綴的變量。這樣所有配置的exe/dll都會(huì)落在build/bin動(dòng)態(tài)庫(kù)和靜態(tài)庫(kù)落在build/lib干凈利落。有個(gè)副作用要注意如果Debug和Release都用同一個(gè)輸出目錄后構(gòu)建的那一個(gè)可能會(huì)覆蓋前一個(gè)的同名DLL。解決辦法是干脆用不同構(gòu)建目錄默認(rèn)不就是build/default和build/release嗎presets里已經(jīng)天然分開了互相不干擾。如果你非要在同一個(gè)構(gòu)建目錄里來(lái)回切換VS的配置那請(qǐng)給DLL加版本后綴或者干脆別合bin目錄省得自找麻煩。4.3 VS工程里的相對(duì)路徑寫法“cmake生成的vs工程使用相對(duì)路徑”這個(gè)痛點(diǎn)我也遇到過(guò)。默認(rèn)情況下VS工程文件里會(huì)寫入很多絕對(duì)路徑比如你的源碼路徑如果從D盤挪到E盤或者拷給別人重新打開工程可能就有一堆紅波浪線、找不到頭文件。CMake其實(shí)是支持相對(duì)路徑的核心原則是在你的CMakeLists.txt里不要寫任何硬編碼絕對(duì)路徑全部基于${CMAKE_CURRENT_SOURCE_DIR}、${CMAKE_CURRENT_BINARY_DIR}、${CMAKE_SOURCE_DIR}來(lái)拼。CMake在生成VS工程時(shí)會(huì)自動(dòng)把能夠相對(duì)化的路徑相對(duì)化。你只要?jiǎng)e手動(dòng)傳一個(gè)D:/projects/...給target_include_directories它生成的工程就是可以整體搬走的。再配合CMAKE_SUPPRESS_REGENERATION或者干脆用Ninja compile_commands.json很多路徑問(wèn)題都會(huì)消失。因?yàn)閏ompile_commands.json里存的路徑是統(tǒng)一基于構(gòu)建目錄的不依賴IDE的工程文件。如果你確實(shí)需要在生成VS工程時(shí)強(qiáng)制使用相對(duì)路徑CMake 3.25之后有了CMAKE_USE_RELATIVE_PATHS這個(gè)選項(xiàng)不過(guò)它默認(rèn)是OFF而且支持得不是特別完美。我的建議是不要在CMakeLists里刻意搞相對(duì)路徑魔法把源碼和構(gòu)建目錄放得層級(jí)關(guān)系穩(wěn)定一些配置里堅(jiān)持用CMake變量引用路徑效果反而最好。4.4 在CMake里執(zhí)行自定義命令或腳本CMake有時(shí)候需要在構(gòu)建前后干點(diǎn)別的活比如生成代碼、拷貝文件、調(diào)腳本。熱搜詞里的“cmake執(zhí)行bash命令”指的就是這類場(chǎng)景。我的模板里尤其是部署腳本大量使用自定義命令這里簡(jiǎn)單說(shuō)一下跨平臺(tái)的做法add_custom_command(TARGET MyQmlApp POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/resources/config $TARGET_FILE_DIR:MyQmlApp/config COMMENT Copying config files )這里不要直接調(diào)bash -c或者cmd /c要用${CMAKE_COMMAND} -E提供的跨平臺(tái)命令集。copy_directory、copy、rm、make_directory這些都有原生的跨平臺(tái)實(shí)現(xiàn)。如果你確實(shí)要調(diào)外部腳本可以用${CMAKE_COMMAND} -E env配合腳本路徑但前提是腳本本身是可移植的不然Windows和Linux一換就崩。這樣設(shè)計(jì)的好處是構(gòu)建腳本可以不用改就在所有平臺(tái)跑。當(dāng)然也不是說(shuō)不能用bash腳本——macOS和Linux上bash天然可用Windows上如果裝了Git Bash也能跑但那就失去了跨平臺(tái)一致性。所以我在模板的CMake部署腳本里盡量用cmake -E原生命令只有像windeployqt這種特定平臺(tái)的工具才按平臺(tái)分支去調(diào)。5. 自動(dòng)打包、windeployqt接入與跨平臺(tái)部署配置QML項(xiàng)目的打包比Widgets項(xiàng)目麻煩這是公認(rèn)的。光是Qt Quick的底層渲染引擎、場(chǎng)景圖插件、QML模塊導(dǎo)入文件這一堆東西手工拷貝就會(huì)漏這漏那。好在CMake可以把這個(gè)過(guò)程自動(dòng)化我模板的cmake/DeployWindows.cmake里專門封裝了一個(gè)函數(shù)構(gòu)建完自動(dòng)執(zhí)行部署輸出一個(gè)可以直接分發(fā)的文件夾。5.1 Windows平臺(tái)windeployqt CMake的POST_BUILD集成windeployqt是Qt Windows平臺(tái)部署的官方工具。它能自動(dòng)掃描exe依賴的Qt DLL、插件、以及QML模塊文件。QML項(xiàng)目使用它有一點(diǎn)必須注意必須指定--qmldir參數(shù)指向你QML源文件的目錄否則工具只會(huì)拷C依賴的DLLQML模塊相關(guān)的文件不會(huì)全部帶齊結(jié)果就是目標(biāo)機(jī)器上exe起來(lái)了但界面空白/報(bào)module not found。下面是我DeployWindows.cmake里的核心片段function(deploy_windows_qt target_name) find_program(WINDEPLOYQT_EXECUTABLE windeployqt HINTS ${QT_BIN_DIR}) if(NOT WINDEPLOYQT_EXECUTABLE) message(FATAL_ERROR windeployqt not found. Check your Qt installation.) endif() set(DEPLOY_BIN_DIR $TARGET_FILE_DIR:${target_name}) add_custom_command(TARGET ${target_name} POST_BUILD COMMAND ${WINDEPLOYQT_EXECUTABLE} --qmldir ${CMAKE_SOURCE_DIR}/qml --release --no-translations --no-system-d3d-compiler --no-opengl-sw $TARGET_FILE:${target_name} WORKING_DIRECTORY ${DEPLOY_BIN_DIR} COMMENT Running windeployqt for ${target_name}... ) add_custom_command(TARGET ${target_name} POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/resources/config ${DEPLOY_BIN_DIR}/config COMMENT Copying runtime config files ) endfunction()用$TARGET_FILE_DIR:${target_name}拿到exe所在目錄的方式非常靈活不會(huì)因?yàn)檩敵瞿夸浉牧硕洹?-release這個(gè)參數(shù)根據(jù)實(shí)際構(gòu)建配置可選如果Debug打包也可以去掉。有幾個(gè)參數(shù)值得展開--no-translations如果項(xiàng)目沒(méi)有做多語(yǔ)言把它加上可以省掉大量qt_*.qm翻譯文件。如果做多語(yǔ)言就不要加并且把resources/translations下生成的app_zh_CN.qm等文件拷過(guò)去。--no-opengl-sw默認(rèn)windeployqt會(huì)把軟件OpenGL的dll也帶過(guò)去如果確定目標(biāo)機(jī)器有GPU驅(qū)動(dòng)這個(gè)參數(shù)可以減小體積但對(duì)一些老舊電腦或者虛擬機(jī)環(huán)境軟件OpenGL反而是救命稻草。要不要加上取決于你的目標(biāo)用戶。我一般發(fā)布給企業(yè)用戶時(shí)是去掉這個(gè)參數(shù)的保險(xiǎn)。5.2 到了部署階段輸出目錄和安裝規(guī)則也要一起搞定如果你的目標(biāo)是做一個(gè)正式的安裝包而不是拷貝文件夾給別人用那就應(yīng)該用CMake的install規(guī)則結(jié)合CPack。下面是一個(gè)install(DIRECTORY ...)的例子install(TARGETS MyQmlApp BUNDLE DESTINATION . RUNTIME DESTINATION bin ) install(DIRECTORY ${CMAKE_BINARY_DIR}/bin/ DESTINATION bin )如果你用了windeployqt把所有依賴都拷到了exe旁邊那install時(shí)就只需要把整個(gè)bin目錄拷貝過(guò)去。Qt官方在6.5之后也支持在qt_add_executable里加QT_DEPLOY_TARGET這種方式但我覺(jué)得在POST_BUILD里執(zhí)行windeployqt更直觀而且對(duì)老版本Qt5.15也兼容。5.3 macOS與Linux的部署說(shuō)明這兩個(gè)平臺(tái)相對(duì)Windows要簡(jiǎn)單一些。macOS上有macdeployqtLinux上有l(wèi)inuxdeployqt社區(qū)維護(hù)。它們的原理都是掃描可執(zhí)行文件的依賴庫(kù)并拷貝到相應(yīng)目錄。在CMake里接入的方式和windeployqt幾乎一樣只是要注意路徑分隔符和工具名不同。macOS下如果用了QML模塊macdeployqt也需要-qmldir參數(shù)。而且從Qt 6開始如果你的應(yīng)用需要提交App Store還要額外處理簽名和sandbox那又是一個(gè)獨(dú)立的主題了。Linux上需要注意的是不同發(fā)行版的庫(kù)版本差異如果目標(biāo)機(jī)器比較舊最好在打包機(jī)上也跑一個(gè)較舊的發(fā)行版容器避免“打包機(jī)太新目標(biāo)機(jī)器跑不了”的尷尬也就是glibc版本太新導(dǎo)致啟動(dòng)報(bào)錯(cuò)。我模板里給Linux用的DeployLinux.cmake大概這樣function(deploy_linux_qt target_name) find_program(LINUXDEPLOYQT_EXECUTABLE linuxdeployqt) if(NOT LINUXDEPLOYQT_EXECUTABLE) message(WARNING linuxdeployqt not found, skip automatic deployment.) return() endif() add_custom_command(TARGET ${target_name} POST_BUILD COMMAND ${LINUXDEPLOYQT_EXECUTABLE} $TARGET_FILE:${target_name} -qmldir${CMAKE_SOURCE_DIR}/qml -appimage WORKING_DIRECTORY $TARGET_FILE_DIR:${target_name} COMMENT Running linuxdeployqt for ${target_name}... ) endfunction()這套邏輯比較直接構(gòu)建完成后跑一次就能得到一個(gè)AppImageLinux下的分發(fā)基本不用操心動(dòng)態(tài)庫(kù)依賴問(wèn)題。6. QML模板開發(fā)中的典型報(bào)錯(cuò)與排查技巧最后這部分我把自己在多個(gè)項(xiàng)目里攢下來(lái)的排錯(cuò)經(jīng)驗(yàn)整理一下。每一條都對(duì)應(yīng)真實(shí)的運(yùn)行/構(gòu)建問(wèn)題能幫你省下大量搜索時(shí)間。6.1 QML模塊找不到import MyQmlApp 1.0 not found這個(gè)報(bào)錯(cuò)在QML項(xiàng)目里出現(xiàn)頻率最高。排查思路按順序來(lái)檢查CMakeLists里qt_add_qml_module的URI和QML文件里import的URI是否完全一致大小寫敏感一個(gè)字母都不能差。檢查RESOURCE_PREFIX設(shè)置是否正確。如果你改了前綴QML文件的導(dǎo)入器搜索路徑也會(huì)跟著變。檢查qt_add_qml_module是否真的被編譯進(jìn)了目標(biāo)。用Qt Creator打開構(gòu)建目錄看能不能找到生成的qmldir文件。找不到就說(shuō)明函數(shù)根本沒(méi)執(zhí)行到。運(yùn)行時(shí)檢查程序輸出看看有沒(méi)有關(guān)于模塊路徑的警告。如果是在Windows上確認(rèn)QML模塊相關(guān)的DLL/文件是否被部署工具拷到了exe旁邊。有一種特別隱蔽的情況模塊A依賴模塊B模塊B沒(méi)被部署工具掃描到導(dǎo)致模塊A的import也一起失敗。這種問(wèn)題通常換一臺(tái)干凈機(jī)器測(cè)一下就能暴露出來(lái)。6.2 QML控件點(diǎn)擊事件報(bào)錯(cuò)之后如何恢復(fù)界面狀態(tài)這個(gè)熱搜詞其實(shí)和CMake模板沒(méi)直接關(guān)系但它其實(shí)是一個(gè)很現(xiàn)實(shí)的QML開發(fā)坑——如果運(yùn)行時(shí)拋了JavaScript異常界面可能卡在一個(gè)異常狀態(tài)里。最靠譜的辦法是在窗口級(jí)別捕獲未處理異常然后重置視圖。簡(jiǎn)單做法是在main.cpp里設(shè)置QQmlEngine的異常鉤子qmlEngine-setNetworkAccessManagerFactory(...) // 不相關(guān) qmlEngine::setErrorCallback? // API各版本不同需查更通用的做法是在QML側(cè)用Qt.application的aboutToQuit等信號(hào)做清理或者在Loader加載頁(yè)面時(shí)包一層異常處理。但這種方式治標(biāo)不治本核心是保證模型層數(shù)據(jù)的一致性比如按鈕點(diǎn)擊里做狀態(tài)翻轉(zhuǎn)時(shí)要先備份再執(zhí)行catch到異常立刻回滾。模板里我建議把這種狀態(tài)管理邏輯下沉到C的AppEngine別寫在QML的onClicked里這樣天然免疫很多異常。6.3 自動(dòng)構(gòu)建過(guò)了但啟動(dòng)白屏或插件加載失敗白屏排查順序和模塊導(dǎo)入類似。第一步先看控制臺(tái)輸出有沒(méi)有Cannot load library ...之類的報(bào)錯(cuò)。第二步檢查Qt插件的目錄結(jié)構(gòu)是否完整。Windows上windeployqt之后exe旁會(huì)有platforms、imageformats、qml等目錄如果目錄不完整應(yīng)用可以啟動(dòng)但界面可能空白。還有一個(gè)坑是Qt版本混用。比如當(dāng)前CMake找到的是Qt 6.6但PATH環(huán)境變量里殘留著一個(gè)Qt 5的bin目錄運(yùn)行時(shí)動(dòng)態(tài)庫(kù)優(yōu)先加載了舊版Qt的DLL導(dǎo)致崩潰或白屏。這種問(wèn)題用ListDLLs這類工具看exe實(shí)際加載的Qt DLL路徑就能確認(rèn)。6.4 CMake配置時(shí)報(bào)Could NOT find Qt6這個(gè)也常見特別是剛裝的Qt。診斷步驟確認(rèn)CMAKE_PREFIX_PATH是否正確指向Qt安裝目錄。比如C:/Qt/6.6.2/msvc2019_64目錄下要有l(wèi)ib/cmake/Qt6/Qt6Config.cmake。檢查是否裝了對(duì)應(yīng)的編譯器ABI。MSVC的Qt庫(kù)只能用MSVC編譯器去找MinGW的Qt庫(kù)只能用MinGW編譯器去找。我見過(guò)有人在VS工程里配了MinGW的Qt路徑CMake怎么都找不到。查看Qt安裝包是否漏裝了我們需要的那幾個(gè)組件。比如只裝了qt6-base沒(méi)裝qt6-quick那find_package(Qt6 COMPONENTS Quick)就會(huì)失敗?？梢栽赒t安裝器里確認(rèn)Quick相關(guān)組件是否勾選。如果找不到可以把CMake錯(cuò)誤信息里的提示貼到Qt安裝目錄確認(rèn)下路徑拼寫。Windows上經(jīng)常出現(xiàn)的就是C:/Qt寫成了C:\Qt在CMake里反斜杠轉(zhuǎn)義很討厭統(tǒng)一用正斜杠。6.5 編譯錯(cuò)誤和自動(dòng)MOC相關(guān)的奇怪問(wèn)題AUTOMOC偶爾會(huì)對(duì)自定義的.h文件產(chǎn)生誤判比如一個(gè)頭文件里有Q_OBJECT但文件后綴不是.h或者它不是一個(gè)完整的類定義。有時(shí)候CMake會(huì)提示Unknown CMake command qt_add_qml_module——這說(shuō)明你用的不是Qt 6或者版本太老沒(méi)有這個(gè)函數(shù)。Qt 6.0是引入qt_add_qml_module的早期版本但真正穩(wěn)定下來(lái)是6.2、6.3。如果你還在Qt 5.15那只能退回qt5_add_resources那套舊寫法或者至少用qt_add_resources加上手工配置qmldir。另外純頭文件的QML類型比如用QML_ELEMENT寫在頭文件里有些版本需要在qt_add_qml_module的SOURCES里同時(shí)列出.h和對(duì)應(yīng)的.cpp否則鏈接期會(huì)報(bào)undefined reference。確保頭文件同時(shí)被AUTOMOC看到這一點(diǎn)別省略。7. 常見問(wèn)題速查表為了讓大家排查起來(lái)更順手我把以上問(wèn)題整理成一張速查表問(wèn)題現(xiàn)象最可能的原因解決方案import 模塊 not foundqmldir沒(méi)有生成或URI不匹配檢查qt_add_qml_module的URI和QML中的import是否一致構(gòu)建成功但啟動(dòng)白屏QML模塊依賴沒(méi)有全部拷貝windeployqt加--qmldir參數(shù)確認(rèn)插件目錄齊全find_package找不到Qt6CMAKE_PREFIX_PATH錯(cuò)誤或ABI不匹配檢查路徑指向msvc/mingw對(duì)應(yīng)目錄確認(rèn)組件完整鏈接期undefined reference to vtableAUTOMOC沒(méi)開或頭文件沒(méi)在SOURCES里確保CMAKE_AUTOMOC ON頭文件和cpp不放漏VS工程換機(jī)器后很多路徑錯(cuò)誤工程里寫死了絕對(duì)路徑配置里改用CMAKE_SOURCE_DIR等變量不要硬編碼路徑輸出目錄多一層Debug/ReleaseVS多配置默認(rèn)輸出路徑帶配置名逐個(gè)配置覆蓋CMAKE_RUNTIME_OUTPUT_DIRECTORYLinux打包后目標(biāo)機(jī)器報(bào)GLIBC錯(cuò)誤打包機(jī)的glibc比目標(biāo)機(jī)器新在較舊的發(fā)行版容器里打包QML類型在界面里看不到?jīng)]有QML_ELEMENT宏或者沒(méi)有注冊(cè)給C類加QML_ELEMENT確保在SOURCES里聲明macdeployqt后庫(kù)加載失敗qt.conf或依賴庫(kù)路徑異常檢查macdeployqt輸出必要時(shí)用otool查看依賴路徑構(gòu)建目錄越來(lái)越大各個(gè)preset輸出混在一起用獨(dú)立的binaryDir或者定期清理build目錄這個(gè)表只覆蓋了高頻問(wèn)題真正復(fù)雜的項(xiàng)目里還會(huì)有很多特殊坑但解決思路是通用的先看CMake配置能不能生成正確的qmldir再看運(yùn)行時(shí)有沒(méi)有找到正確的模塊/插件目錄最后才懷疑代碼本身。最后再分享一個(gè)小技巧。如果你只是想在幾分鐘內(nèi)跑起一個(gè)QML小項(xiàng)目做驗(yàn)證不需要整套模板可以試試只用這幾行CMakecmake_minimum_required(VERSION 3.24) project(TestQml) set(CMAKE_AUTOMOC ON) find_package(Qt6 REQUIRED COMPONENTS Quick) qt_standard_project_setup() qt_add_executable(TestQml main.cpp) qt_add_qml_module(TestQml URI TestQml QML_FILES Main.qml) qt_finalize_executable(TestQml)這個(gè)極簡(jiǎn)模板也踩過(guò)了Qt 6.5和6.6的坑能跑通。真正的完整模板就是把這一套再加上目錄劃分、部署腳本、Presets和測(cè)試框架。我自己在實(shí)際項(xiàng)目里最滿意的不是某一行命令而是整套路清晰構(gòu)建、運(yùn)行、打包、測(cè)試每件事都有明確的入口和出口。照著這個(gè)思路搭不管項(xiàng)目后面膨脹成什么樣地基都不會(huì)歪。