1. 從一個(gè)讓人抓狂的編譯報(bào)錯(cuò)說(shuō)起如果你寫過C尤其是用Qt寫桌面端項(xiàng)目大概率遇到過這種場(chǎng)景代碼在IDE里看著一切正常頭文件路徑有高亮函數(shù)跳轉(zhuǎn)也能用但一按編譯按鈕滿屏的紅色錯(cuò)誤就撲面而來(lái)——fatal error: xxx.h: No such file or directory或者鏈接階段突然告訴你undefined reference to xxx。你明明記得這個(gè)庫(kù)昨天還能用今天換了個(gè)目錄結(jié)構(gòu)就全崩了。這就是Qt設(shè)置引用路徑問題的典型表現(xiàn)。它不是什么高深的技術(shù)難題但絕對(duì)是消耗開發(fā)者耐心最多的“日?？印敝弧Ｎ乙娺^不少工作兩三年的開發(fā)者每次遇到路徑問題還是靠“瞎試”——加個(gè)INCLUDEPATH不行就加LIBSLIBS不行就改.pro文件順序最后碰巧編譯過了但問他為什么能過他說(shuō)不上來(lái)。這篇文章想解決的問題很具體把Qt項(xiàng)目中引用路徑的配置邏輯徹底講清楚。包括頭文件路徑、庫(kù)文件路徑、運(yùn)行時(shí)路徑這三類核心路徑分別在什么階段起作用qmake和CMake兩套構(gòu)建系統(tǒng)下怎么配置以及跨平臺(tái)Windows、Linux、macOS時(shí)路徑寫法有什么差異。適合所有正在用Qt做項(xiàng)目、被路徑問題折磨過、或者想提前避坑的開發(fā)者。不管你是剛接觸Qt的新手還是用了幾年但一直沒系統(tǒng)梳理過路徑配置的老手下面這些內(nèi)容應(yīng)該都能幫你省下不少查資料和試錯(cuò)的時(shí)間。2. 為什么路徑配置這么容易出問題2.1 編譯期、鏈接期、運(yùn)行期的路徑是三件不同的事很多人把“引用路徑”當(dāng)成一個(gè)籠統(tǒng)的概念這是所有混亂的根源。實(shí)際上一個(gè)Qt項(xiàng)目從源碼到可執(zhí)行程序路徑在三個(gè)完全不同的階段發(fā)揮作用每個(gè)階段由不同的工具處理配置方式也完全不同。編譯期處理的是頭文件路徑。編譯器需要找到#include指令引用的.h或.hpp文件。這個(gè)階段由INCLUDEPATHqmake或target_include_directoriesCMake控制。如果這里配錯(cuò)了報(bào)錯(cuò)就是fatal error: xxx.h: No such file or directory。鏈接期處理的是庫(kù)文件路徑。鏈接器需要找到.lib、.a、.so、.dylib這些二進(jìn)制庫(kù)文件把符號(hào)引用解析成實(shí)際地址。這個(gè)階段由LIBSqmake或target_link_librariesCMake控制。配錯(cuò)了就是undefined reference或cannot find -lxxx。運(yùn)行期處理的是動(dòng)態(tài)庫(kù)加載路徑。程序啟動(dòng)時(shí)操作系統(tǒng)需要找到它依賴的動(dòng)態(tài)庫(kù)。Windows下是.dllLinux下是.somacOS下是.dylib。這個(gè)階段跟構(gòu)建系統(tǒng)沒關(guān)系了取決于系統(tǒng)的庫(kù)搜索機(jī)制。配錯(cuò)了就是程序啟動(dòng)時(shí)報(bào)“找不到xxx.dll”或者“error while loading shared libraries”。我剛開始用Qt的時(shí)候最常犯的錯(cuò)誤就是把這三個(gè)階段混在一起。比如編譯通過了、鏈接也通過了但一運(yùn)行就崩潰然后回頭去改INCLUDEPATH完全改錯(cuò)了方向。后來(lái)我才養(yǎng)成習(xí)慣看到報(bào)錯(cuò)先判斷是哪個(gè)階段的問題再去改對(duì)應(yīng)的配置。這個(gè)判斷習(xí)慣至少幫我節(jié)省了一半的排查時(shí)間。2.2 qmake和CMake的路徑處理邏輯差異Qt早期項(xiàng)目幾乎都用qmake.pro文件是標(biāo)配?，F(xiàn)在新項(xiàng)目越來(lái)越多用CMakeQt官方從Qt6開始也主推CMake。兩套系統(tǒng)處理路徑的邏輯有本質(zhì)區(qū)別不能混著理解。qmake的路徑處理相對(duì)“扁平”。你在.pro文件里寫的INCLUDEPATH ./includeqmake會(huì)把它轉(zhuǎn)換成編譯命令的-I參數(shù)。相對(duì)路徑的基準(zhǔn)是.pro文件所在的目錄。LIBS -L./lib -lmylib同理-L指定庫(kù)搜索目錄-l指定庫(kù)名。qmake不太區(qū)分“構(gòu)建目錄”和“源碼目錄”相對(duì)路徑的解析規(guī)則比較直觀但也容易在影子構(gòu)建shadow build時(shí)出問題。CMake的路徑處理更“結(jié)構(gòu)化”。它區(qū)分CMAKE_SOURCE_DIR、CMAKE_BINARY_DIR、CMAKE_CURRENT_SOURCE_DIR等多個(gè)路徑變量還有target_include_directories的PUBLIC、PRIVATE、INTERFACE作用域區(qū)分。好處是大型項(xiàng)目管理更清晰壞處是學(xué)習(xí)曲線陡。很多人從qmake轉(zhuǎn)到CMake時(shí)最不適應(yīng)的就是“為什么我寫的相對(duì)路徑找不到文件”——因?yàn)镃Make的相對(duì)路徑基準(zhǔn)可能不是你以為的那個(gè)目錄。提示如果你在CMake項(xiàng)目里用相對(duì)路徑永遠(yuǎn)用${CMAKE_CURRENT_SOURCE_DIR}或${CMAKE_CURRENT_BINARY_DIR}做前綴不要直接寫./xxx。這是我從無(wú)數(shù)次“本地能編譯、CI上掛掉”的教訓(xùn)里總結(jié)出來(lái)的。2.3 跨平臺(tái)帶來(lái)的路徑分隔符和搜索規(guī)則差異Windows用反斜杠\做路徑分隔符Linux和macOS用正斜杠/。雖然Qt和大多數(shù)構(gòu)建工具在內(nèi)部會(huì)做轉(zhuǎn)換但你在.pro或CMakeLists.txt里寫路徑時(shí)最好統(tǒng)一用正斜杠/。qmake和CMake都能正確識(shí)別正斜杠但反斜杠在CMake里是轉(zhuǎn)義字符容易出幺蛾子。更麻煩的是動(dòng)態(tài)庫(kù)的搜索規(guī)則。Windows下可執(zhí)行文件會(huì)先在當(dāng)前目錄找.dll然后按PATH環(huán)境變量找。Linux下LD_LIBRARY_PATH環(huán)境變量和/etc/ld.so.conf配置決定搜索路徑當(dāng)前目錄默認(rèn)不在搜索范圍內(nèi)。macOS用DYLD_LIBRARY_PATH和rpath機(jī)制。這些差異導(dǎo)致同一個(gè)項(xiàng)目在不同平臺(tái)上可能需要不同的運(yùn)行時(shí)路徑配置。我做過一個(gè)跨三平臺(tái)的項(xiàng)目最頭疼的就是macOS的rpath。Windows和Linux下配好LIBS就能跑macOS下編譯鏈接都沒問題一運(yùn)行就報(bào)dyld: Library not loaded。后來(lái)才搞明白需要在鏈接時(shí)加-rpath參數(shù)把庫(kù)的運(yùn)行時(shí)搜索路徑寫進(jìn)可執(zhí)行文件。這個(gè)坑我踩了整整一個(gè)下午查了無(wú)數(shù)資料才搞定。3. qmake下的路徑配置實(shí)操3.1 INCLUDEPATH的正確寫法與常見誤區(qū)INCLUDEPATH是qmake里最常用的路徑變量控制編譯器的頭文件搜索路徑?；緦懛ê芎?jiǎn)單INCLUDEPATH ./include INCLUDEPATH ../thirdparty/libxml2/include INCLUDEPATH /usr/local/include/opencv4但這里有幾個(gè)容易踩的坑。第一個(gè)坑是相對(duì)路徑的基準(zhǔn)問題。qmake解析INCLUDEPATH里的相對(duì)路徑時(shí)基準(zhǔn)是當(dāng)前.pro文件所在的目錄不是構(gòu)建目錄。這在影子構(gòu)建時(shí)容易讓人困惑——你的源碼在/home/user/project構(gòu)建目錄在/home/user/project/build.pro里寫INCLUDEPATH ./includeqmake會(huì)解析成/home/user/project/include而不是/home/user/project/build/include。這個(gè)行為其實(shí)是合理的但如果你習(xí)慣了某些IDE的“相對(duì)于構(gòu)建目錄”邏輯就會(huì)覺得別扭。第二個(gè)坑是路徑末尾不要加斜杠。INCLUDEPATH ./include/和INCLUDEPATH ./include在大多數(shù)情況下效果一樣但某些qmake版本或某些平臺(tái)下末尾斜杠可能導(dǎo)致路徑拼接時(shí)出現(xiàn)雙斜杠雖然編譯器通常能處理但看著不舒服也可能在某些工具鏈下出問題。統(tǒng)一不加末尾斜杠是好習(xí)慣。第三個(gè)坑是順序問題。INCLUDEPATH的搜索順序是按添加順序來(lái)的。如果你有兩個(gè)目錄下有同名頭文件先添加的目錄會(huì)被優(yōu)先搜索。這個(gè)特性有時(shí)候能救命——比如你想覆蓋某個(gè)第三方庫(kù)的頭文件把自己的目錄加在前面就行。但更多時(shí)候它是麻煩的來(lái)源——你以為用的是A版本的頭文件實(shí)際上編譯器找到了B版本的。我建議在.pro文件里給INCLUDEPATH加注釋標(biāo)明每個(gè)路徑的用途方便后續(xù)排查。# 項(xiàng)目自身頭文件 INCLUDEPATH $$PWD/src INCLUDEPATH $$PWD/include # 第三方庫(kù)頭文件 INCLUDEPATH $$PWD/thirdparty/json/include INCLUDEPATH $$PWD/thirdparty/spdlog/include這里用了$$PWD它是qmake的內(nèi)置變量表示當(dāng)前.pro文件所在目錄的絕對(duì)路徑。用$$PWD代替.的好處是路徑永遠(yuǎn)是絕對(duì)的不受構(gòu)建目錄影響也不會(huì)有相對(duì)路徑解析的歧義。我強(qiáng)烈建議在所有INCLUDEPATH和LIBS里都用$$PWD做前綴這是最穩(wěn)妥的做法。3.2 LIBS的配置細(xì)節(jié)與鏈接順序陷阱LIBS變量控制鏈接器的庫(kù)搜索路徑和要鏈接的庫(kù)。典型寫法LIBS -L$$PWD/thirdparty/json/lib -ljsoncpp LIBS -L$$PWD/thirdparty/spdlog/lib -lspdlog-L指定庫(kù)文件所在目錄-l指定庫(kù)名不帶前綴和后綴。比如-ljsoncpp會(huì)讓鏈接器去找libjsoncpp.soLinux、libjsoncpp.a靜態(tài)庫(kù)、jsoncpp.libWindows或libjsoncpp.dylibmacOS。鏈接順序是這里最大的陷阱。GNU鏈接器Linux下處理庫(kù)的順序是從左到右如果庫(kù)A依賴庫(kù)B那么-lA必須出現(xiàn)在-lB前面。寫反了就會(huì)報(bào)undefined reference。這個(gè)規(guī)則在Windows的MSVC鏈接器下不那么嚴(yán)格但在Linux和macOS下必須遵守。# 正確依賴方在前被依賴方在后 LIBS -lmyapp -lmybase # 錯(cuò)誤被依賴方在前可能導(dǎo)致undefined reference LIBS -lmybase -lmyapp如果庫(kù)之間有循環(huán)依賴可以用--start-group和--end-group包裹LIBS -Wl,--start-group -lA -lB -lC -Wl,--end-group但循環(huán)依賴本身通常是設(shè)計(jì)問題能避免就避免。另一個(gè)細(xì)節(jié)是Windows下Debug和Release庫(kù)的區(qū)分。MSVC編譯的庫(kù)通常帶d后綴表示Debug版本比如mylibd.lib和mylib.lib。在.pro里可以用條件判斷CONFIG(debug, debug|release) { LIBS -L$$PWD/lib/debug -lmylibd } else { LIBS -L$$PWD/lib/release -lmylib }這個(gè)寫法在跨平臺(tái)項(xiàng)目里很實(shí)用但要注意MinGW編譯器不一定遵循d后綴約定需要根據(jù)實(shí)際庫(kù)文件名調(diào)整。3.3 運(yùn)行時(shí)庫(kù)路徑的三種處理方式編譯鏈接都過了程序一運(yùn)行報(bào)“找不到動(dòng)態(tài)庫(kù)”這是運(yùn)行時(shí)路徑問題。qmake本身不直接處理運(yùn)行時(shí)路徑但你可以通過幾種方式解決。方式一把動(dòng)態(tài)庫(kù)復(fù)制到可執(zhí)行文件旁邊。這是最簡(jiǎn)單粗暴的方法在Windows下特別有效因?yàn)閃indows默認(rèn)會(huì)在可執(zhí)行文件所在目錄搜索.dll。在.pro里可以加自定義構(gòu)建步驟自動(dòng)復(fù)制win32 { QMAKE_POST_LINK $$quote(cmd /c copy /y $$shell_path($$PWD/thirdparty/json/lib/jsoncpp.dll) $$shell_path($$OUT_PWD/release/)) }方式二設(shè)置rpathLinux和macOS。rpath是寫在可執(zhí)行文件里的運(yùn)行時(shí)庫(kù)搜索路徑。qmake可以通過QMAKE_RPATHDIR設(shè)置unix:!macx { QMAKE_RPATHDIR $$PWD/thirdparty/json/lib } macx { QMAKE_RPATHDIR executable_path/../Frameworks }Linux下還可以用$ORIGIN表示可執(zhí)行文件所在目錄QMAKE_RPATHDIR $ORIGIN/lib這樣程序會(huì)去可執(zhí)行文件旁邊的lib目錄找動(dòng)態(tài)庫(kù)部署時(shí)把庫(kù)放在對(duì)應(yīng)位置就行。方式三設(shè)置環(huán)境變量。Linux下用LD_LIBRARY_PATHmacOS下用DYLD_LIBRARY_PATHWindows下用PATH。這種方式適合開發(fā)調(diào)試階段不適合最終部署因?yàn)橐笥脩羰謩?dòng)配置環(huán)境變量。# Linux下臨時(shí)設(shè)置 export LD_LIBRARY_PATH/path/to/libs:$LD_LIBRARY_PATH ./myapp我個(gè)人的習(xí)慣是開發(fā)階段用方式三快速驗(yàn)證確認(rèn)庫(kù)沒問題后改用方式二rpath做正式配置Windows下用方式一。這樣既方便調(diào)試又保證部署時(shí)不需要額外配置。4. CMake下的路徑配置實(shí)操4.1 target_include_directories的作用域與最佳實(shí)踐CMake里配置頭文件路徑用target_include_directories比qmake的INCLUDEPATH多了一個(gè)作用域概念target_include_directories(myapp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src ${CMAKE_CURRENT_SOURCE_DIR}/include ) target_include_directories(myapp PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/api ) target_include_directories(myapp INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/interface )PRIVATE表示這些路徑只用于編譯當(dāng)前target不傳遞給依賴它的其他target。PUBLIC表示既用于當(dāng)前target也傳遞給依賴它的target。INTERFACE表示不用于當(dāng)前target只傳遞給依賴它的target。這個(gè)機(jī)制在大型項(xiàng)目里非常有用。比如你寫了一個(gè)庫(kù)mylib它的公開頭文件在include/目錄私有頭文件在src/目錄。那么target_include_directories(mylib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src )這樣依賴mylib的其他target會(huì)自動(dòng)獲得include/的搜索路徑但不會(huì)獲得src/的路徑。封裝性很好。但這里有個(gè)常見誤區(qū)很多人把所有路徑都寫成PUBLIC導(dǎo)致路徑污染。比如你把第三方庫(kù)的路徑寫成PUBLIC所有依賴你的target都會(huì)去搜索那個(gè)第三方庫(kù)的路徑可能引發(fā)頭文件沖突。我的原則是只把確實(shí)需要暴露給外部的路徑設(shè)為PUBLIC其余一律PRIVATE。4.2 target_link_libraries的依賴傳遞與寫法CMake里鏈接庫(kù)用target_link_librariestarget_link_libraries(myapp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib/libjsoncpp.a ) target_link_libraries(myapp PRIVATE jsoncpp spdlog )可以直接寫庫(kù)文件的完整路徑也可以寫庫(kù)名讓CMake去搜索。寫庫(kù)名時(shí)需要用link_directories指定搜索路徑link_directories(${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib) target_link_libraries(myapp PRIVATE jsoncpp)但link_directories的作用范圍是當(dāng)前目錄及子目錄而且不推薦在現(xiàn)代CMake中使用。更好的做法是用find_package或add_subdirectory引入第三方庫(kù)讓CMake自動(dòng)處理路徑。如果第三方庫(kù)沒有提供CMake支持可以手動(dòng)創(chuàng)建IMPORTEDtargetadd_library(jsoncpp STATIC IMPORTED) set_target_properties(jsoncpp PROPERTIES IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib/libjsoncpp.a INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/include ) target_link_libraries(myapp PRIVATE jsoncpp)這樣就把庫(kù)文件和頭文件路徑綁定在一起了用起來(lái)更干凈。4.3 運(yùn)行時(shí)路徑的CMake處理方案CMake設(shè)置rpath用INSTALL_RPATH和BUILD_RPATHset_target_properties(myapp PROPERTIES BUILD_RPATH ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib INSTALL_RPATH $ORIGIN/lib )BUILD_RPATH用于構(gòu)建階段的運(yùn)行INSTALL_RPATH用于安裝后的運(yùn)行。$ORIGIN在Linux下表示可執(zhí)行文件所在目錄macOS下用executable_path。Windows下CMake可以配置構(gòu)建后事件復(fù)制DLLadd_custom_command(TARGET myapp POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib/jsoncpp.dll $TARGET_FILE_DIR:myapp )這個(gè)寫法比qmake的QMAKE_POST_LINK更清晰而且跨平臺(tái)兼容性更好。5. 路徑問題排查實(shí)戰(zhàn)5.1 編譯期報(bào)錯(cuò)頭文件找不到的排查流程看到fatal error: xxx.h: No such file or directory按以下步驟排查第一步確認(rèn)頭文件是否真的存在于你配置的路徑下。有時(shí)候是文件根本沒下載全或者路徑拼寫錯(cuò)了。我遇到過把include寫成includes的情況找了半天才發(fā)現(xiàn)。第二步確認(rèn)INCLUDEPATH或target_include_directories是否真的生效了。qmake下可以運(yùn)行qmake -d查看詳細(xì)輸出CMake下可以用cmake --build . --verbose查看實(shí)際編譯命令。編譯命令里會(huì)包含-I參數(shù)看看你配置的路徑在不在里面。第三步檢查路徑分隔符和大小寫。Windows下路徑不區(qū)分大小寫Linux下區(qū)分。如果你在Windows下開發(fā)代碼里寫#include MyHeader.h但實(shí)際文件名是myheader.hWindows下能編譯Linux下就報(bào)錯(cuò)。第四步檢查是否有多個(gè)同名頭文件沖突。用編譯命令里的-I參數(shù)順序結(jié)合gcc -E -v查看頭文件搜索路徑的完整列表。5.2 鏈接期報(bào)錯(cuò)undefined reference的排查思路undefined reference to xxx說(shuō)明鏈接器找到了庫(kù)文件但庫(kù)里沒有這個(gè)符號(hào)?？赡艿脑驇?kù)文件版本不對(duì)比如鏈接了Release版但需要Debug版的符號(hào)庫(kù)文件架構(gòu)不對(duì)比如在64位項(xiàng)目里鏈接了32位庫(kù)鏈接順序問題依賴方寫在了被依賴方后面C符號(hào)修飾name mangling問題比如C庫(kù)沒有用extern C包裹排查方法用nm命令查看庫(kù)文件里的符號(hào)nm -C libmylib.a | grep xxx如果符號(hào)存在但鏈接還是報(bào)錯(cuò)大概率是鏈接順序問題。如果符號(hào)不存在說(shuō)明庫(kù)文件不對(duì)。5.3 運(yùn)行期報(bào)錯(cuò)動(dòng)態(tài)庫(kù)加載失敗的排查方法Linux下用ldd查看可執(zhí)行文件的動(dòng)態(tài)庫(kù)依賴ldd ./myapp輸出里如果有not found說(shuō)明對(duì)應(yīng)的庫(kù)找不到。然后用readelf -d ./myapp | grep RPATH查看rpath配置。macOS下用otool -L ./myapp查看依賴otool -l ./myapp | grep -A2 LC_RPATH查看rpath。Windows下用dumpbin /dependents myapp.exe查看依賴的DLL。這些工具能幫你快速定位是哪個(gè)庫(kù)找不到以及當(dāng)前的搜索路徑是什么。5.4 常見問題速查表報(bào)錯(cuò)信息發(fā)生階段可能原因解決方法fatal error: xxx.h: No such file or directory編譯期INCLUDEPATH未配置或路徑錯(cuò)誤檢查INCLUDEPATH用$$PWD做前綴cannot find -lxxx鏈接期LIBS的-L路徑錯(cuò)誤或庫(kù)文件不存在檢查-L路徑和庫(kù)文件名undefined reference to xxx鏈接期鏈接順序錯(cuò)誤或庫(kù)版本不匹配調(diào)整鏈接順序檢查庫(kù)版本error while loading shared libraries運(yùn)行期動(dòng)態(tài)庫(kù)搜索路徑未配置設(shè)置rpath或LD_LIBRARY_PATHdyld: Library not loaded運(yùn)行期macOS rpath未配置設(shè)置QMAKE_RPATHDIR或INSTALL_RPATH程序啟動(dòng)閃退無(wú)報(bào)錯(cuò)運(yùn)行期Windows下DLL缺失用dumpbin檢查依賴復(fù)制DLL到exe目錄6. 幾個(gè)讓我印象深刻的踩坑經(jīng)歷6.1 影子構(gòu)建導(dǎo)致的相對(duì)路徑失效有一次我接手一個(gè)項(xiàng)目.pro文件里寫的是INCLUDEPATH ./include。在源碼目錄下直接構(gòu)建沒問題但換成影子構(gòu)建在單獨(dú)的build目錄里執(zhí)行qmake就報(bào)頭文件找不到。原因是qmake解析./include時(shí)基準(zhǔn)是.pro文件所在目錄但某些qmake版本在影子構(gòu)建時(shí)會(huì)把基準(zhǔn)解析成構(gòu)建目錄。后來(lái)我把所有相對(duì)路徑都改成$$PWD/include問題徹底解決。這個(gè)經(jīng)歷讓我養(yǎng)成了一個(gè)習(xí)慣永遠(yuǎn)不在構(gòu)建配置里寫裸的相對(duì)路徑一律用$$PWD或${CMAKE_CURRENT_SOURCE_DIR}做前綴。多打幾個(gè)字符省下的是幾小時(shí)的排查時(shí)間。6.2 鏈接順序引發(fā)的“靈異事件”一個(gè)項(xiàng)目在Windows下編譯鏈接都正常到了Linux下就報(bào)undefined reference。查了半天發(fā)現(xiàn)是鏈接順序問題Windows的MSVC鏈接器對(duì)庫(kù)順序不敏感Linux的GNU鏈接器嚴(yán)格按順序解析。把LIBS里的庫(kù)順序調(diào)整了一下就好了。這件事教會(huì)我跨平臺(tái)項(xiàng)目要以最嚴(yán)格的平臺(tái)為準(zhǔn)來(lái)寫配置。Linux的鏈接器最嚴(yán)格按它的規(guī)則寫Windows和macOS基本都不會(huì)出問題。6.3 macOS的rpath配置踩坑記macOS的rpath機(jī)制跟Linux不一樣它用rpath、executable_path、loader_path這幾個(gè)特殊變量。我第一次在macOS上配動(dòng)態(tài)庫(kù)路徑時(shí)按Linux的經(jīng)驗(yàn)設(shè)了QMAKE_RPATHDIR結(jié)果編譯鏈接都過運(yùn)行時(shí)報(bào)dyld: Library not loaded。后來(lái)查資料才知道m(xù)acOS需要在鏈接時(shí)加-rpath參數(shù)而且路徑要用executable_path開頭。正確的配置是macx { QMAKE_LFLAGS -Wl,-rpath,executable_path/../Frameworks QMAKE_RPATHDIR executable_path/../Frameworks }這樣可執(zhí)行文件會(huì)去上級(jí)目錄的Frameworks文件夾找動(dòng)態(tài)庫(kù)。部署時(shí)把庫(kù)放在那個(gè)位置就行。7. 一些實(shí)用的配置建議7.1 項(xiàng)目目錄結(jié)構(gòu)規(guī)范一個(gè)清晰的目錄結(jié)構(gòu)能避免很多路徑問題。我常用的結(jié)構(gòu)是project/ ├── src/ # 源碼 ├── include/ # 公開頭文件 ├── thirdparty/ # 第三方庫(kù) │ ├── json/ │ │ ├── include/ │ │ └── lib/ │ └── spdlog/ │ ├── include/ │ └── lib/ ├── build/ # 構(gòu)建目錄影子構(gòu)建 └── myapp.pro第三方庫(kù)統(tǒng)一放在thirdparty下每個(gè)庫(kù)有獨(dú)立的include和lib子目錄。這樣INCLUDEPATH和LIBS的配置就很規(guī)整INCLUDEPATH $$PWD/include INCLUDEPATH $$PWD/thirdparty/json/include INCLUDEPATH $$PWD/thirdparty/spdlog/include LIBS -L$$PWD/thirdparty/json/lib -ljsoncpp LIBS -L$$PWD/thirdparty/spdlog/lib -lspdlog7.2 環(huán)境變量與構(gòu)建配置的分離不要把機(jī)器相關(guān)的路徑硬編碼在.pro或CMakeLists.txt里。比如/home/username/libs這種路徑換臺(tái)機(jī)器就失效了?？梢杂铆h(huán)境變量JSONCPP_DIR $$(JSONCPP_DIR) isEmpty(JSONCPP_DIR) { JSONCPP_DIR $$PWD/thirdparty/json } INCLUDEPATH $$JSONCPP_DIR/include LIBS -L$$JSONCPP_DIR/lib -ljsoncpp這樣默認(rèn)用項(xiàng)目?jī)?nèi)的第三方庫(kù)需要時(shí)可以通過環(huán)境變量覆蓋。CI/CD環(huán)境下特別有用。7.3 用qmake的system()做路徑檢查qmake支持在配置階段執(zhí)行shell命令可以用來(lái)做路徑存在性檢查!exists($$PWD/thirdparty/json/include/json/json.h) { error(jsoncpp headers not found. Please run setup script.) }這樣如果第三方庫(kù)沒準(zhǔn)備好qmake階段就會(huì)報(bào)錯(cuò)而不是等到編譯時(shí)才報(bào)頭文件找不到。錯(cuò)誤信息也更明確。路徑配置這件事說(shuō)到底就是“知道每個(gè)路徑在哪個(gè)階段起作用然后用最穩(wěn)妥的方式寫”。我見過太多人在這上面反復(fù)踩坑其實(shí)只要把編譯期、鏈接期、運(yùn)行期這三個(gè)階段分清楚再記住$$PWD和${CMAKE_CURRENT_SOURCE_DIR}這兩個(gè)“萬(wàn)能前綴”大部分問題都能避免。剩下那些跨平臺(tái)的差異遇到一次記一次慢慢就形成條件反射了。