境搭建全攻略：從版本選型到常見錯誤根治)
1. 先想清楚你學(xué)的到底是哪一個QT5版本、界面框架和編譯器套件的三岔路口很多人打開QT5的下載頁面就懵了原因很簡單——你在搜索引擎里敲“QT5下載”的時候腦子里想的其實是“一個叫QT的東西”但等你真正落到官網(wǎng)看到的是好幾套東西混在一起有Qt 5.9.4、5.12、5.15這些版本號有MSVC 2017 64-bit、MinGW 7.3.0這種編譯器標(biāo)識還有QML、Quick、Widgets這些從來沒見過的名詞。不先把這三層關(guān)系捋清楚后面每一步都會踩坑而且你連自己錯在哪都說不出來。先看版本。QT5是個大版本家族從5.0到5.15中間隔了十多個minor release。網(wǎng)上搜“QT5安裝”搜出來的教程還停留在5.9.4這種2017年前后的老版本這里面有個很現(xiàn)實的原因很多學(xué)校的嵌入式課件、老的C項目文檔都是拿5.9.4寫的所以老教程滿天飛。但你自己新學(xué)的話我的建議是直接上5.15.2這是QT5的最后一個LTS長期支持版本官方一直維護到2025年。相比之下5.9.4雖然也穩(wěn)定但已經(jīng)是晚期維護狀態(tài)了很多新模塊的新特性沒有而且最重要的是——5.9.4時代配的Qt Creator版本老后面我們要講的“無法拖拽文件”這種毛病在老版本上特別容易觸發(fā)。版本選新不選舊這條原則在QT5這里同樣適用除非你被某個老項目的代碼綁死了否則沒有理由用5.9.4。再說界面框架。QT5里有兩條完全不同的路一個是Qt Widgets基于C控件體系的傳統(tǒng)桌面界面方案QPushButton、QLineEdit、QTableWidget這些都是Widgets寫起來和MFC的思路有一點點像控件直接往窗口上擺。另一個是Qt Quick / QML這是用聲明式語法描述界面、用JavaScript寫邏輯的框架更適合做觸摸設(shè)備、炫酷動效和跨端界面。你搜“QT5藍圖”的時候大概率是被傳統(tǒng)桌面開發(fā)吸引過來的那么老老實實走Widgets路線就夠了QML可以等Widgets玩熟了再碰。兩條路不是二選一的仇敵很多項目混著用但對新手來說先專一。我見過不少新人上來就想搞QML結(jié)果因為QML的基礎(chǔ)——JavaScript、QObject屬性系統(tǒng)、Context——還沒建立學(xué)了半天連個按鈕的點擊響應(yīng)都寫不順打擊信心不說還白費了時間。最后是編譯器套件。MSVC 2017 64-bit和MinGW之間的選擇本質(zhì)是你用哪套編譯器來構(gòu)建你的C代碼。MSVC是微軟的Visual C編譯器在Windows上跑QT5程序性能好、兼容性好但你需要裝對應(yīng)版本的Visual Studio——最少裝Build Tools否則光有QT5編譯器套件也編不過。MinGW是Windows上的GCC移植版好處是輕量裝完QT直接就能編不需要額外安裝幾GB的VS。我的建議很簡單如果你電腦上已經(jīng)裝了Visual Studio或者以后打算把C基礎(chǔ)功打好選MSVC如果你只是想快點跑起來、不想被VS的體積折磨選MinGW。但注意一點——你裝的是MSVC編譯出來的QT5就必須用MSVC套件構(gòu)建你的工程MinGW同理混著來就會遇到下面要說的那一堆moc、qrc、頭文件路徑的詭異問題。2. 下載安裝那一步不少人是敗在組件勾選上——把Qt WebEngine這些模塊一次配齊明白了上面三個概念再去看下載頁就順暢多了。老版本的QT5沒有在線安裝器官方打包成好幾十個exe文件放在archive里一個主包加一堆子模塊包下得人頭皮發(fā)麻。5.15之后官方主推在線安裝器下載一個qt-unified-windows-x64版本剩下的組件在安裝界面里自己勾選。這里要特別提醒一件事網(wǎng)上所有教你“勾全選”的教程都是在害你QT5組件全選拉下來二三十GB里面一半的模塊你這輩子都用不上。但反過來漏勾也很疼——熱搜里那個“qt5安裝webengineview”就是典型地安裝時可以沒用用時方恨少。Qt WebEngine是個什么東西簡單說它是把Chromium瀏覽器內(nèi)核塞進了QT5里讓你能在桌面程序里渲染HTML頁面、跑JavaScript、做富文本編輯器甚至直接內(nèi)置一個瀏覽器。很多新手裝完QT5之后寫了個QWebEngineView結(jié)果一import就報錯跑起來直接崩就是因為裝QT5的時候沒勾WebEngine相關(guān)模塊。這個模塊在在線安裝器的組件樹里Qt - Qt WebEngine分類下要把那個復(fù)選框整個勾上——注意不是只勾主模塊Qt WebEngine的Debug庫和源碼也要勾不然你后面想在IDE里跟蹤進庫代碼斷點根本進不去。除了WebEngine還有兩個組件絕對不要漏。一個是Sources很多人嫌占空間不勾這個我強烈建議勾上幾百MB換一個隨時查看QT5源碼的能力排錯的時候價值無可估量。另一個是與你選定的編譯器版本對應(yīng)的開發(fā)庫比如選了MSVC 2017 64-bit那msvc2017_64目錄下的Qt庫文件是必選的核心這個默認就會裝上但要注意別只勾個Runtime不勾Development。另外QT5還帶一套Qt Creator IDE這部分默認勾選不用動。安裝目錄這一個看起來無所謂的細節(jié)我勸你務(wù)必上心。默認路徑通常帶空格比如C:\Program Files\Qt這在大多數(shù)時候沒問題但如果以后你走CMake 自定義腳本構(gòu)建那條路帶空格的路徑偶爾會惹出一些引號沒加夠的奇奇怪怪問題。我自己習(xí)慣裝成C:\Qt\Qt5.15.2這種無空格短路徑一勞永逸。路徑里不要有中文這條不用多說了吧凡是編譯相關(guān)的工具鏈中文路徑都能給你編出一堆莫名其妙的錯。裝完還有一個環(huán)境變量的動作老手可能默認你知道了但新手經(jīng)常漏。安裝器在安裝過程中會把Qt Creator的啟動程序放進開始菜單但不會幫你設(shè)置QTDIR、PATH這些環(huán)境變量。你要手動把C:\Qt\Qt5.15.2\5.15.2\msvc2017_64\bin加進系統(tǒng)的PATH否則后面在命令行里手敲qmake、windeployqt這些工具會提示找不到命令。做法是右鍵“此電腦” - 屬性 - 高級系統(tǒng)設(shè)置 - 環(huán)境變量在系統(tǒng)變量的Path里追加那一條改完最好重啟一次終端窗口讓它生效。3. 從新建工程到看見第一個窗口構(gòu)建套件與qmake的工作方式環(huán)境裝好之后第一件事不是去翻API文檔而是先跑通一個最簡單的窗口。打開Qt Creator界面可能有點復(fù)雜但你要找的關(guān)鍵入口就兩個左上角的“New Project”和左側(cè)工具條里的“Welcome”。點New Project左側(cè)列表選“Application”中間選“Qt Widgets Application”這個是經(jīng)典起步模板。點確定后會讓你選項目保存位置——注意這里有個很多人忽略的問題整個項目路徑同樣別帶中文和空格否則后面單步調(diào)試時符號表加載會坑你路徑最好清清爽爽的比如D:\code\helloworld。再往后是Kit選擇頁面這里會列出你安裝QT5時配置好的構(gòu)建套件。如果你裝的MSVC版這里會出現(xiàn)Desktop Qt 5.15.2 MSVC2017 64bit這一項如果是MinGW版則是帶MinGW字樣的套件。選好之后一直下一步直到完成。Qt Creator會自動幫你生成main.cpp、mainwindow.cpp、mainwindow.h外加一個.pro工程文件和一個mainwindow.ui界面描述文件。直接點左下角的綠色三角“運行”按鈕如果一切順利幾秒鐘后屏幕上出現(xiàn)一個空蕩蕩的窗口——恭喜你的第一個QT5程序活了。這個“活了”的背后其實藏著QT5一個和其他C框架很不一樣的工作流程值得稍微展開講一下因為它搞懂了你后面調(diào)試各種詭異報錯就有的放矢了。QT5的項目構(gòu)建不是簡單的“編譯器讀cpp - 產(chǎn)出exe”這么一步。Qt處理的是C的超集概念你在代碼里寫的Q_OBJECT宏、signals關(guān)鍵字、slots關(guān)鍵字、tr()翻譯函數(shù)這些都不是標(biāo)準(zhǔn)C語法C編譯器本身根本不認識。所以Qt會先用自己的工具mocMeta-Object Compiler元對象編譯器掃描頭文件遇到含有Q_OBJECT宏的頭文件自動生成一個額外的moc_xxx.cpp文件遇到資源文件.qrcrcc工具會把資源編譯進代碼遇到.ui界面文件uic工具會把它轉(zhuǎn)成ui_xxx.h。這些生成的中間文件再加上你的源碼才會一起交給真正的編譯器去編譯鏈接。這套機制的結(jié)果是QT5工程不能只盯著自己寫的cpp文件構(gòu)建目錄里躺著的一大堆moc_開頭、qrc_開頭的文件才是Qt真正干活的證據(jù)。在新版的Qt Creator里這些都是自動完成的你不需要關(guān)心。但有個常見的翻車點值得知道如果你把一個含Q_OBJECT宏的頭文件加入工程卻沒有在.pro文件里聲明HEADERS那么moc不會生成對應(yīng)的moc文件編譯時你會看到一堆奇怪的“undefined reference to vtable”錯誤——這種報錯經(jīng)驗豐富的人一眼就知道是“漏了Q_OBJECT處理”但你第一次遇見時絕對一頭霧水。跑通之后千萬別急著關(guān)趁熱做兩個小實驗這兩個實驗?zāi)茏屇銓T5的事件循環(huán)和對象模型有直覺。第一個實驗在mainwindow.cpp的構(gòu)造函數(shù)里加一行ui-setupUi(this);后面跟一句setWindowTitle(QStringLiteral(藍圖系列第一站));重新運行看看窗口標(biāo)題有沒有變成那行字。第二個實驗在MainWindow的構(gòu)造函數(shù)里new一個QLabel塞進centralwidget文本設(shè)為“Hello Qt 5”再運行。親眼看到代碼變成窗口里的一個控件之后你對“代碼構(gòu)建界面”這件事就開始有體感了后面怎么寫UI都不會怕。4. .pro文件、構(gòu)建目錄和那個神秘的qt5config.cmake路徑跑通第一個工程后把項目文件面板展開你會看到一個以項目名命名的.pro文件它的內(nèi)容大概是幾行整齊的配置QT core gui、greaterThan(QT_MAJOR_VERSION, 4): QT widgets、TARGET helloworld、TEMPLATE app后面跟著SOURCES、HEADERS、FORMS三個變量列著你的文件。很多人忽略這個文件認為IDE管理一切但這個文件是qmake理解你這個項目的唯一入口很多疑難雜癥的根子都在這里。QT 那一塊是你向qmake聲明“我要用Qt的哪些模塊”這行配置直接和你的鏈接庫對應(yīng)。你寫了個QWebEngineView如果不加QT webenginewidgets編譯時就會報“找不到webenginewidgets模塊”之類的錯這時正確的做法不是去IDE設(shè)置里亂翻而是回到.pro文件補上這一行。這就是為什么網(wǎng)上所有QT5問題討論帖幾乎都會先回一句“你的.pro里加了xx模塊沒有”——這是排序第一的排查點。再往下你可能會在項目目錄旁邊注意到一個帶著build-前綴的同名目錄那是Qt Creator的構(gòu)建目錄。qmake默認采用“影子構(gòu)建”機制就是源碼目錄和構(gòu)建目錄分離——源文件在D:\code\helloworld中間產(chǎn)物和最終exe則躺在D:\code\build-helloworld-Desktop_Qt_5_15_2_MSVC2017_64bit-Debug目錄里。初次接觸時可能覺得多此一舉搞這么長的怪目錄名。實際上這是個非常聰明的設(shè)計好處是顯而易見的你不小心把構(gòu)建目錄整個刪了源碼毫發(fā)無損再構(gòu)建一次又從零來一個源頭能同時保留Debug和Release兩套構(gòu)建產(chǎn)物互不干擾。我自己就經(jīng)歷過只配置Debug不配置Release到發(fā)版本時一跑Release全是debug版本的殘留行為尷尬得很。但影子構(gòu)建也有它坑人的一面尤其是那些試圖在構(gòu)建目錄里找文件、或者腳本硬編碼了相對路徑的項目一挪窩就炸。所以你會發(fā)現(xiàn)很多老項目干脆放棄影子構(gòu)建在.pro里寫一行DESTDIR $$PWD/bin把exe統(tǒng)一輸出到源碼目錄下的bin文件夾里——兩種風(fēng)格都有自己的道理看項目習(xí)慣。接下來要說的這個路徑問題直接回應(yīng)一下熱搜詞里出現(xiàn)頻率很高的“cmake error at c:/qt/qt5.9.4/5.9.4/msvc2017_64/lib/cmake/qt5/qt5config.cmake”。這個報錯本身很好讀懂某個CMake工程在配置階段試圖去加載qt5config.cmake這個文件——Qt5的CMake配置入口——但CMake說找不到。這句話里的路徑特別有迷惑性因為它的拼寫是C:\qt\qt5.9.4\5.9.4\msvc2017_64\lib\cmake\qt5看起來好像是Qt安裝程序自己寫死的路徑缺文件于是你順著找過去發(fā)現(xiàn)文件確實不在那。但是別急著重裝真正的問題是這個C:\qt并不是你裝有Qt的目錄而是某個機器上曾經(jīng)存在過的目錄而這份CMake配置是從別人的工程里拷出來的。換句話說報錯里的路徑只是“上次在某臺機器上Qt被安裝的位置”和你現(xiàn)在的Qt安裝在哪毫無關(guān)系。正確的解決辦法完全不需要碰這個舊路徑如果是CMake工程設(shè)置變量CMAKE_PREFIX_PATH指向你Qt真正的安裝前綴假設(shè)你的Qt裝在了D:\Qt\5.15.2\msvc2017_64那么打開CMake配置時在CMakeLists里或cmake命令行里指定-DCMAKE_PREFIX_PATHD:\Qt\5.15.2\msvc2017_64重新configure系統(tǒng)會到$prefix/lib/cmake/Qt5Qt5Config.cmake或者更準(zhǔn)確地說是到$prefix/lib/cmake/qt5目錄下找qt5config.cmake自然就配上了。如果用的是qmake系那就沒有這個困擾因為qmake的路徑配置在安裝時由安裝器寫入了Qt Creator的構(gòu)建套件里IDE會老老實實找到對應(yīng)版本的qmake——這也是為什么我強烈建議初學(xué)階段用qmake而不是CMake的原因少踩一大串配置坑。5. 老版本Qt Creator的兩個歷史遺留問題拖拽失效與路徑報錯的現(xiàn)實解法熱搜里有兩組詞初看會莫名其妙一個是“qt5無法拖拽文件”另一個就是這幾版creator常見的構(gòu)建/運行路徑報錯。這些問題的共同點讓人有些無奈——它們都不是QT5框架本身的bug而是Qt Creator這個IDE在特定版本、特定系統(tǒng)環(huán)境下的老毛病。先說“無法拖拽文件”。我說的是在文件資源管理器里選中一個源碼文件拖動到Qt Creator的編輯器窗口里松開鼠標(biāo)期望它打開文件。在有些版本上你會發(fā)現(xiàn)鼠標(biāo)拖過去、指針變成禁止符號怎么都放不進去。解決辦法要分軟件層面和系統(tǒng)層面。軟件層面先確認你是哪個版本5.9.4自帶的Qt Creator版本相當(dāng)老這種拖拽失效幾乎成了老版本的標(biāo)志性問題升級到5.15.2對應(yīng)的Creator版本后基本就自愈了。系統(tǒng)層面如果你確認Creator版本夠新仍然拖不動那就去檢查Qt Creator運行時的權(quán)限——如果它是用管理員身份啟動的而你的資源管理器是普通權(quán)限在Windows的session 0隔離和UIPI機制下跨權(quán)限拖拽數(shù)據(jù)交換就會被拒絕。這是Windows自己的機制在起作用和Qt Creator一點關(guān)系沒有。遇到這種情況把Qt Creator從“以管理員身份運行”改為普通權(quán)限啟動就能解決。如果實在解決不了再分享一個完全不依賴拖拽的操作路徑——在資源管理器中選中文件右鍵選“Open With”在程序列表里選Qt Creator或者干脆用最基礎(chǔ)的辦法打開Qt Creator按下CtrlO在彈出的文件對話框里手動導(dǎo)航到目標(biāo)文件。雖然效率低了點但穩(wěn)定可靠。我見過有人因為一個拖拽問題在論壇里翻了十幾頁舊帖最后發(fā)現(xiàn)是殺毒軟件把拖拽卸載的hook給劫持了所以別被一個小交互卡太久。另一處老版本的歷史遺留問題是工程運行時的“構(gòu)建套件路徑錯亂”——具體表現(xiàn)是構(gòu)建成功exe也生成了但點擊運行時提示找不到某個Qt5Core.dll或者提示找不到qwindows.dll。初學(xué)者看到dll缺失就四處找dll、復(fù)制dll這完全是治標(biāo)不治本。根因在于系統(tǒng)PATH里沒有Qt的bin目錄或者Qt Creator運行時選擇的套件環(huán)境沒有被正確匹配到。打開“工具”菜單進“Kits”檢查當(dāng)前使用的套件里Qt version那一欄是否真的指向了你安裝的實打?qū)嵉腝t目錄而不是某個殘留的無效路徑。bin目錄加進系統(tǒng)PATH后重啟Qt Creator再運行dll缺失的問題基本不會再出現(xiàn)。6. 接下來怎么走第一階段QT5學(xué)習(xí)路線與排錯自查表文章最后這段寫給看完上面內(nèi)容、剛剛跑通第一個窗口的你。我先把話放前面明白了框架和工具怎么用和真正能在QT5里開發(fā)出有用的程序之間還有相當(dāng)長的一段距離但這段路是有明確路標(biāo)可走的不需要什么高深的天賦耐心按節(jié)奏推進就行。我的建議是第一階段集中火力搞定四件事這四件事是按依賴順序排好的不建議跳。第一件是控件基礎(chǔ)QPushButton、QLabel、QLineEdit、QTextEdit、QListWidget這幾個高頻控件挨個放上去看看行為和屬性面板不需要背API大概長什么樣、觸發(fā)什么信號心里有數(shù)就行。第二件是布局管理QVBoxLayout、QHBoxLayout、QGridLayout三個布局搞定能做到窗口拉伸時控件跟著合理伸縮這時候你對父控件、控件樹結(jié)構(gòu)會有一個真實的體感。第三件是信號槽機制這是QT5的靈魂connect函數(shù)的五種寫法Lambda表達式怎么捕獲變量傳參數(shù)按鈕點擊怎么更新label文字這一步你值得慢因為在QT里所有UI交互的響應(yīng)都在信號槽上轉(zhuǎn)。第四件是樣式表QSSQT5的界面美化基本靠它做一個像樣的登錄頁面給自己一點正反饋。排錯能力也是第一階段的必修課我把這段高頻問題整理成一張表你出問題時直接對著找能省下大量翻論壇的時間常見報錯/現(xiàn)象最可能的原因首選檢查動作編譯報 vtable/undefined reference頭文件含Q_OBJECT但沒寫進HEADERS檢查.pro文件的HEADERS列表QWebEngineView使用時崩潰或找不到模塊安裝時沒勾Qt WebEngine重跑安裝器補裝WebEngine模塊運行時提示缺少Q(mào)t5Core.dll等bin目錄未進PATH或套件路徑無效檢查系統(tǒng)PATH和“工具 - Kits”里的Qt版本路徑CMake找不到qt5config.cmakeCMAKE_PREFIX_PATH未指向Qt安裝前綴配置-DCMAKE_PREFIX_PATH指向你的Qt目錄點擊運行時窗口一閃而過可能是構(gòu)建成功了但啟動崩潰在Qt Creator里切到“應(yīng)用程序輸出”面板看崩潰信息中文路徑導(dǎo)致moc或編譯器無法處理項目路徑或源碼路徑含中文遷到純英文路徑后重新構(gòu)建整個QT5的學(xué)習(xí)曲線最有意思的地方在于前期最陡的不是C語法而是那套對象模型和構(gòu)建流程帶來的“黑盒感”。當(dāng)你親手處理完上面表格里任意三四個問題之后QT5在你眼里就不再是黑盒了。第一個真正屬于自己的小項目比你自己想的要近。我個人的體會是QT5學(xué)習(xí)的節(jié)奏不在于每天背多少API而是保持一個“每天都在產(chǎn)出可見程序”的頻率。哪怕今天只學(xué)會了把按鈕文字的字體變大也是一個能拿得出手的成果。就憑現(xiàn)在這些積累你已經(jīng)能構(gòu)建起一個能跑、能調(diào)試、能排查基本問題的QT5環(huán)境了。下一篇“藍圖二”我會帶你繼續(xù)往前推一步把信號槽的細節(jié)和常用控件的搭配組合講透到時候我們工程里見。 QT5環(huán)境搭建全攻略：從版本選型到常見錯誤根治
1. 先想清楚你學(xué)的到底是哪一個QT5版本、界面框架和編譯器套件的三岔路口很多人打開QT5的下載頁面就懵了原因很簡單——你在搜索引擎里敲“QT5下載”的時候腦子里想的其實是“一個叫QT的東西”但等你真正落到官網(wǎng)看到的是好幾套東西混在一起有Qt 5.9.4、5.12、5.15這些版本號有MSVC 2017 64-bit、MinGW 7.3.0這種編譯器標(biāo)識還有QML、Quick、Widgets這些從來沒見過的名詞。不先把這三層關(guān)系捋清楚后面每一步都會踩坑而且你連自己錯在哪都說不出來。先看版本。QT5是個大版本家族從5.0到5.15中間隔了十多個minor release。網(wǎng)上搜“QT5安裝”搜出來的教程還停留在5.9.4這種2017年前后的老版本這里面有個很現(xiàn)實的原因很多學(xué)校的嵌入式課件、老的C項目文檔都是拿5.9.4寫的所以老教程滿天飛。但你自己新學(xué)的話我的建議是直接上5.15.2這是QT5的最后一個LTS長期支持版本官方一直維護到2025年。相比之下5.9.4雖然也穩(wěn)定但已經(jīng)是晚期維護狀態(tài)了很多新模塊的新特性沒有而且最重要的是——5.9.4時代配的Qt Creator版本老后面我們要講的“無法拖拽文件”這種毛病在老版本上特別容易觸發(fā)。版本選新不選舊這條原則在QT5這里同樣適用除非你被某個老項目的代碼綁死了否則沒有理由用5.9.4。再說界面框架。QT5里有兩條完全不同的路一個是Qt Widgets基于C控件體系的傳統(tǒng)桌面界面方案QPushButton、QLineEdit、QTableWidget這些都是Widgets寫起來和MFC的思路有一點點像控件直接往窗口上擺。另一個是Qt Quick / QML這是用聲明式語法描述界面、用JavaScript寫邏輯的框架更適合做觸摸設(shè)備、炫酷動效和跨端界面。你搜“QT5藍圖”的時候大概率是被傳統(tǒng)桌面開發(fā)吸引過來的那么老老實實走Widgets路線就夠了QML可以等Widgets玩熟了再碰。兩條路不是二選一的仇敵很多項目混著用但對新手來說先專一。我見過不少新人上來就想搞QML結(jié)果因為QML的基礎(chǔ)——JavaScript、QObject屬性系統(tǒng)、Context——還沒建立學(xué)了半天連個按鈕的點擊響應(yīng)都寫不順打擊信心不說還白費了時間。最后是編譯器套件。MSVC 2017 64-bit和MinGW之間的選擇本質(zhì)是你用哪套編譯器來構(gòu)建你的C代碼。MSVC是微軟的Visual C編譯器在Windows上跑QT5程序性能好、兼容性好但你需要裝對應(yīng)版本的Visual Studio——最少裝Build Tools否則光有QT5編譯器套件也編不過。MinGW是Windows上的GCC移植版好處是輕量裝完QT直接就能編不需要額外安裝幾GB的VS。我的建議很簡單如果你電腦上已經(jīng)裝了Visual Studio或者以后打算把C基礎(chǔ)功打好選MSVC如果你只是想快點跑起來、不想被VS的體積折磨選MinGW。但注意一點——你裝的是MSVC編譯出來的QT5就必須用MSVC套件構(gòu)建你的工程MinGW同理混著來就會遇到下面要說的那一堆moc、qrc、頭文件路徑的詭異問題。2. 下載安裝那一步不少人是敗在組件勾選上——把Qt WebEngine這些模塊一次配齊明白了上面三個概念再去看下載頁就順暢多了。老版本的QT5沒有在線安裝器官方打包成好幾十個exe文件放在archive里一個主包加一堆子模塊包下得人頭皮發(fā)麻。5.15之后官方主推在線安裝器下載一個qt-unified-windows-x64版本剩下的組件在安裝界面里自己勾選。這里要特別提醒一件事網(wǎng)上所有教你“勾全選”的教程都是在害你QT5組件全選拉下來二三十GB里面一半的模塊你這輩子都用不上。但反過來漏勾也很疼——熱搜里那個“qt5安裝webengineview”就是典型地安裝時可以沒用用時方恨少。Qt WebEngine是個什么東西簡單說它是把Chromium瀏覽器內(nèi)核塞進了QT5里讓你能在桌面程序里渲染HTML頁面、跑JavaScript、做富文本編輯器甚至直接內(nèi)置一個瀏覽器。很多新手裝完QT5之后寫了個QWebEngineView結(jié)果一import就報錯跑起來直接崩就是因為裝QT5的時候沒勾WebEngine相關(guān)模塊。這個模塊在在線安裝器的組件樹里Qt - Qt WebEngine分類下要把那個復(fù)選框整個勾上——注意不是只勾主模塊Qt WebEngine的Debug庫和源碼也要勾不然你后面想在IDE里跟蹤進庫代碼斷點根本進不去。除了WebEngine還有兩個組件絕對不要漏。一個是Sources很多人嫌占空間不勾這個我強烈建議勾上幾百MB換一個隨時查看QT5源碼的能力排錯的時候價值無可估量。另一個是與你選定的編譯器版本對應(yīng)的開發(fā)庫比如選了MSVC 2017 64-bit那msvc2017_64目錄下的Qt庫文件是必選的核心這個默認就會裝上但要注意別只勾個Runtime不勾Development。另外QT5還帶一套Qt Creator IDE這部分默認勾選不用動。安裝目錄這一個看起來無所謂的細節(jié)我勸你務(wù)必上心。默認路徑通常帶空格比如C:\Program Files\Qt這在大多數(shù)時候沒問題但如果以后你走CMake 自定義腳本構(gòu)建那條路帶空格的路徑偶爾會惹出一些引號沒加夠的奇奇怪怪問題。我自己習(xí)慣裝成C:\Qt\Qt5.15.2這種無空格短路徑一勞永逸。路徑里不要有中文這條不用多說了吧凡是編譯相關(guān)的工具鏈中文路徑都能給你編出一堆莫名其妙的錯。裝完還有一個環(huán)境變量的動作老手可能默認你知道了但新手經(jīng)常漏。安裝器在安裝過程中會把Qt Creator的啟動程序放進開始菜單但不會幫你設(shè)置QTDIR、PATH這些環(huán)境變量。你要手動把C:\Qt\Qt5.15.2\5.15.2\msvc2017_64\bin加進系統(tǒng)的PATH否則后面在命令行里手敲qmake、windeployqt這些工具會提示找不到命令。做法是右鍵“此電腦” - 屬性 - 高級系統(tǒng)設(shè)置 - 環(huán)境變量在系統(tǒng)變量的Path里追加那一條改完最好重啟一次終端窗口讓它生效。3. 從新建工程到看見第一個窗口構(gòu)建套件與qmake的工作方式環(huán)境裝好之后第一件事不是去翻API文檔而是先跑通一個最簡單的窗口。打開Qt Creator界面可能有點復(fù)雜但你要找的關(guān)鍵入口就兩個左上角的“New Project”和左側(cè)工具條里的“Welcome”。點New Project左側(cè)列表選“Application”中間選“Qt Widgets Application”這個是經(jīng)典起步模板。點確定后會讓你選項目保存位置——注意這里有個很多人忽略的問題整個項目路徑同樣別帶中文和空格否則后面單步調(diào)試時符號表加載會坑你路徑最好清清爽爽的比如D:\code\helloworld。再往后是Kit選擇頁面這里會列出你安裝QT5時配置好的構(gòu)建套件。如果你裝的MSVC版這里會出現(xiàn)Desktop Qt 5.15.2 MSVC2017 64bit這一項如果是MinGW版則是帶MinGW字樣的套件。選好之后一直下一步直到完成。Qt Creator會自動幫你生成main.cpp、mainwindow.cpp、mainwindow.h外加一個.pro工程文件和一個mainwindow.ui界面描述文件。直接點左下角的綠色三角“運行”按鈕如果一切順利幾秒鐘后屏幕上出現(xiàn)一個空蕩蕩的窗口——恭喜你的第一個QT5程序活了。這個“活了”的背后其實藏著QT5一個和其他C框架很不一樣的工作流程值得稍微展開講一下因為它搞懂了你后面調(diào)試各種詭異報錯就有的放矢了。QT5的項目構(gòu)建不是簡單的“編譯器讀cpp - 產(chǎn)出exe”這么一步。Qt處理的是C的超集概念你在代碼里寫的Q_OBJECT宏、signals關(guān)鍵字、slots關(guān)鍵字、tr()翻譯函數(shù)這些都不是標(biāo)準(zhǔn)C語法C編譯器本身根本不認識。所以Qt會先用自己的工具mocMeta-Object Compiler元對象編譯器掃描頭文件遇到含有Q_OBJECT宏的頭文件自動生成一個額外的moc_xxx.cpp文件遇到資源文件.qrcrcc工具會把資源編譯進代碼遇到.ui界面文件uic工具會把它轉(zhuǎn)成ui_xxx.h。這些生成的中間文件再加上你的源碼才會一起交給真正的編譯器去編譯鏈接。這套機制的結(jié)果是QT5工程不能只盯著自己寫的cpp文件構(gòu)建目錄里躺著的一大堆moc_開頭、qrc_開頭的文件才是Qt真正干活的證據(jù)。在新版的Qt Creator里這些都是自動完成的你不需要關(guān)心。但有個常見的翻車點值得知道如果你把一個含Q_OBJECT宏的頭文件加入工程卻沒有在.pro文件里聲明HEADERS那么moc不會生成對應(yīng)的moc文件編譯時你會看到一堆奇怪的“undefined reference to vtable”錯誤——這種報錯經(jīng)驗豐富的人一眼就知道是“漏了Q_OBJECT處理”但你第一次遇見時絕對一頭霧水。跑通之后千萬別急著關(guān)趁熱做兩個小實驗這兩個實驗?zāi)茏屇銓T5的事件循環(huán)和對象模型有直覺。第一個實驗在mainwindow.cpp的構(gòu)造函數(shù)里加一行ui-setupUi(this);后面跟一句setWindowTitle(QStringLiteral(藍圖系列第一站));重新運行看看窗口標(biāo)題有沒有變成那行字。第二個實驗在MainWindow的構(gòu)造函數(shù)里new一個QLabel塞進centralwidget文本設(shè)為“Hello Qt 5”再運行。親眼看到代碼變成窗口里的一個控件之后你對“代碼構(gòu)建界面”這件事就開始有體感了后面怎么寫UI都不會怕。4. .pro文件、構(gòu)建目錄和那個神秘的qt5config.cmake路徑跑通第一個工程后把項目文件面板展開你會看到一個以項目名命名的.pro文件它的內(nèi)容大概是幾行整齊的配置QT core gui、greaterThan(QT_MAJOR_VERSION, 4): QT widgets、TARGET helloworld、TEMPLATE app后面跟著SOURCES、HEADERS、FORMS三個變量列著你的文件。很多人忽略這個文件認為IDE管理一切但這個文件是qmake理解你這個項目的唯一入口很多疑難雜癥的根子都在這里。QT 那一塊是你向qmake聲明“我要用Qt的哪些模塊”這行配置直接和你的鏈接庫對應(yīng)。你寫了個QWebEngineView如果不加QT webenginewidgets編譯時就會報“找不到webenginewidgets模塊”之類的錯這時正確的做法不是去IDE設(shè)置里亂翻而是回到.pro文件補上這一行。這就是為什么網(wǎng)上所有QT5問題討論帖幾乎都會先回一句“你的.pro里加了xx模塊沒有”——這是排序第一的排查點。再往下你可能會在項目目錄旁邊注意到一個帶著build-前綴的同名目錄那是Qt Creator的構(gòu)建目錄。qmake默認采用“影子構(gòu)建”機制就是源碼目錄和構(gòu)建目錄分離——源文件在D:\code\helloworld中間產(chǎn)物和最終exe則躺在D:\code\build-helloworld-Desktop_Qt_5_15_2_MSVC2017_64bit-Debug目錄里。初次接觸時可能覺得多此一舉搞這么長的怪目錄名。實際上這是個非常聰明的設(shè)計好處是顯而易見的你不小心把構(gòu)建目錄整個刪了源碼毫發(fā)無損再構(gòu)建一次又從零來一個源頭能同時保留Debug和Release兩套構(gòu)建產(chǎn)物互不干擾。我自己就經(jīng)歷過只配置Debug不配置Release到發(fā)版本時一跑Release全是debug版本的殘留行為尷尬得很。但影子構(gòu)建也有它坑人的一面尤其是那些試圖在構(gòu)建目錄里找文件、或者腳本硬編碼了相對路徑的項目一挪窩就炸。所以你會發(fā)現(xiàn)很多老項目干脆放棄影子構(gòu)建在.pro里寫一行DESTDIR $$PWD/bin把exe統(tǒng)一輸出到源碼目錄下的bin文件夾里——兩種風(fēng)格都有自己的道理看項目習(xí)慣。接下來要說的這個路徑問題直接回應(yīng)一下熱搜詞里出現(xiàn)頻率很高的“cmake error at c:/qt/qt5.9.4/5.9.4/msvc2017_64/lib/cmake/qt5/qt5config.cmake”。這個報錯本身很好讀懂某個CMake工程在配置階段試圖去加載qt5config.cmake這個文件——Qt5的CMake配置入口——但CMake說找不到。這句話里的路徑特別有迷惑性因為它的拼寫是C:\qt\qt5.9.4\5.9.4\msvc2017_64\lib\cmake\qt5看起來好像是Qt安裝程序自己寫死的路徑缺文件于是你順著找過去發(fā)現(xiàn)文件確實不在那。但是別急著重裝真正的問題是這個C:\qt并不是你裝有Qt的目錄而是某個機器上曾經(jīng)存在過的目錄而這份CMake配置是從別人的工程里拷出來的。換句話說報錯里的路徑只是“上次在某臺機器上Qt被安裝的位置”和你現(xiàn)在的Qt安裝在哪毫無關(guān)系。正確的解決辦法完全不需要碰這個舊路徑如果是CMake工程設(shè)置變量CMAKE_PREFIX_PATH指向你Qt真正的安裝前綴假設(shè)你的Qt裝在了D:\Qt\5.15.2\msvc2017_64那么打開CMake配置時在CMakeLists里或cmake命令行里指定-DCMAKE_PREFIX_PATHD:\Qt\5.15.2\msvc2017_64重新configure系統(tǒng)會到$prefix/lib/cmake/Qt5Qt5Config.cmake或者更準(zhǔn)確地說是到$prefix/lib/cmake/qt5目錄下找qt5config.cmake自然就配上了。如果用的是qmake系那就沒有這個困擾因為qmake的路徑配置在安裝時由安裝器寫入了Qt Creator的構(gòu)建套件里IDE會老老實實找到對應(yīng)版本的qmake——這也是為什么我強烈建議初學(xué)階段用qmake而不是CMake的原因少踩一大串配置坑。5. 老版本Qt Creator的兩個歷史遺留問題拖拽失效與路徑報錯的現(xiàn)實解法熱搜里有兩組詞初看會莫名其妙一個是“qt5無法拖拽文件”另一個就是這幾版creator常見的構(gòu)建/運行路徑報錯。這些問題的共同點讓人有些無奈——它們都不是QT5框架本身的bug而是Qt Creator這個IDE在特定版本、特定系統(tǒng)環(huán)境下的老毛病。先說“無法拖拽文件”。我說的是在文件資源管理器里選中一個源碼文件拖動到Qt Creator的編輯器窗口里松開鼠標(biāo)期望它打開文件。在有些版本上你會發(fā)現(xiàn)鼠標(biāo)拖過去、指針變成禁止符號怎么都放不進去。解決辦法要分軟件層面和系統(tǒng)層面。軟件層面先確認你是哪個版本5.9.4自帶的Qt Creator版本相當(dāng)老這種拖拽失效幾乎成了老版本的標(biāo)志性問題升級到5.15.2對應(yīng)的Creator版本后基本就自愈了。系統(tǒng)層面如果你確認Creator版本夠新仍然拖不動那就去檢查Qt Creator運行時的權(quán)限——如果它是用管理員身份啟動的而你的資源管理器是普通權(quán)限在Windows的session 0隔離和UIPI機制下跨權(quán)限拖拽數(shù)據(jù)交換就會被拒絕。這是Windows自己的機制在起作用和Qt Creator一點關(guān)系沒有。遇到這種情況把Qt Creator從“以管理員身份運行”改為普通權(quán)限啟動就能解決。如果實在解決不了再分享一個完全不依賴拖拽的操作路徑——在資源管理器中選中文件右鍵選“Open With”在程序列表里選Qt Creator或者干脆用最基礎(chǔ)的辦法打開Qt Creator按下CtrlO在彈出的文件對話框里手動導(dǎo)航到目標(biāo)文件。雖然效率低了點但穩(wěn)定可靠。我見過有人因為一個拖拽問題在論壇里翻了十幾頁舊帖最后發(fā)現(xiàn)是殺毒軟件把拖拽卸載的hook給劫持了所以別被一個小交互卡太久。另一處老版本的歷史遺留問題是工程運行時的“構(gòu)建套件路徑錯亂”——具體表現(xiàn)是構(gòu)建成功exe也生成了但點擊運行時提示找不到某個Qt5Core.dll或者提示找不到qwindows.dll。初學(xué)者看到dll缺失就四處找dll、復(fù)制dll這完全是治標(biāo)不治本。根因在于系統(tǒng)PATH里沒有Qt的bin目錄或者Qt Creator運行時選擇的套件環(huán)境沒有被正確匹配到。打開“工具”菜單進“Kits”檢查當(dāng)前使用的套件里Qt version那一欄是否真的指向了你安裝的實打?qū)嵉腝t目錄而不是某個殘留的無效路徑。bin目錄加進系統(tǒng)PATH后重啟Qt Creator再運行dll缺失的問題基本不會再出現(xiàn)。6. 接下來怎么走第一階段QT5學(xué)習(xí)路線與排錯自查表文章最后這段寫給看完上面內(nèi)容、剛剛跑通第一個窗口的你。我先把話放前面明白了框架和工具怎么用和真正能在QT5里開發(fā)出有用的程序之間還有相當(dāng)長的一段距離但這段路是有明確路標(biāo)可走的不需要什么高深的天賦耐心按節(jié)奏推進就行。我的建議是第一階段集中火力搞定四件事這四件事是按依賴順序排好的不建議跳。第一件是控件基礎(chǔ)QPushButton、QLabel、QLineEdit、QTextEdit、QListWidget這幾個高頻控件挨個放上去看看行為和屬性面板不需要背API大概長什么樣、觸發(fā)什么信號心里有數(shù)就行。第二件是布局管理QVBoxLayout、QHBoxLayout、QGridLayout三個布局搞定能做到窗口拉伸時控件跟著合理伸縮這時候你對父控件、控件樹結(jié)構(gòu)會有一個真實的體感。第三件是信號槽機制這是QT5的靈魂connect函數(shù)的五種寫法Lambda表達式怎么捕獲變量傳參數(shù)按鈕點擊怎么更新label文字這一步你值得慢因為在QT里所有UI交互的響應(yīng)都在信號槽上轉(zhuǎn)。第四件是樣式表QSSQT5的界面美化基本靠它做一個像樣的登錄頁面給自己一點正反饋。排錯能力也是第一階段的必修課我把這段高頻問題整理成一張表你出問題時直接對著找能省下大量翻論壇的時間常見報錯/現(xiàn)象最可能的原因首選檢查動作編譯報 vtable/undefined reference頭文件含Q_OBJECT但沒寫進HEADERS檢查.pro文件的HEADERS列表QWebEngineView使用時崩潰或找不到模塊安裝時沒勾Qt WebEngine重跑安裝器補裝WebEngine模塊運行時提示缺少Q(mào)t5Core.dll等bin目錄未進PATH或套件路徑無效檢查系統(tǒng)PATH和“工具 - Kits”里的Qt版本路徑CMake找不到qt5config.cmakeCMAKE_PREFIX_PATH未指向Qt安裝前綴配置-DCMAKE_PREFIX_PATH指向你的Qt目錄點擊運行時窗口一閃而過可能是構(gòu)建成功了但啟動崩潰在Qt Creator里切到“應(yīng)用程序輸出”面板看崩潰信息中文路徑導(dǎo)致moc或編譯器無法處理項目路徑或源碼路徑含中文遷到純英文路徑后重新構(gòu)建整個QT5的學(xué)習(xí)曲線最有意思的地方在于前期最陡的不是C語法而是那套對象模型和構(gòu)建流程帶來的“黑盒感”。當(dāng)你親手處理完上面表格里任意三四個問題之后QT5在你眼里就不再是黑盒了。第一個真正屬于自己的小項目比你自己想的要近。我個人的體會是QT5學(xué)習(xí)的節(jié)奏不在于每天背多少API而是保持一個“每天都在產(chǎn)出可見程序”的頻率。哪怕今天只學(xué)會了把按鈕文字的字體變大也是一個能拿得出手的成果。就憑現(xiàn)在這些積累你已經(jīng)能構(gòu)建起一個能跑、能調(diào)試、能排查基本問題的QT5環(huán)境了。下一篇“藍圖二”我會帶你繼續(xù)往前推一步把信號槽的細節(jié)和常用控件的搭配組合講透到時候我們工程里見。