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