簡介cpr-1.3.0 預編譯庫面向使用 C 發(fā)起 HTTP 請求的開發(fā)者適合在 VS 項目中快速接入、又不想自行編譯 cpr 與 libcurl 的初、中級人員。壓縮包共 27 個文件含 21 個頭文件、4 個 lib 靜態(tài)庫和 2 個 dll 動態(tài)庫Debug/Release 均提供 cpr.lib、libcurl.dll 等整體約 738KB便于隨工程歸檔引用。資源由 weststarqp 于 2019 年 2 月基于 VS2015 編譯已有 691 人學習。解壓后可按配置將頭文件、庫文件與動態(tài)庫加入工程減少搭建依賴環(huán)境的時間并借助頭文件了解 session、response、auth、cookies 等接口為請求封裝和調試提供基礎。1. 從一次庫在頭文件不在的編譯失敗說起上周接手一個內部工具的構建CMakeLists 里一行find_package(cpr REQUIRED)我以為是十分鐘的事結果make直接甩出一堆fatal error: cpr/generated/cpr_generated_includes.h: No such file or directory。庫文件明明裝了頭文件目錄也加進-I了偏偏缺一個名字很長的中間頭文件。這就是 cpr 1.3.0 最經典的一關。cpr 全稱 C Requests是把 libcurl 那套 C 接口包成cpr::Get/cpr::Response風格的 C11 庫寫 HTTP 客戶端時不用再和curl_easy_setopt的變參列表較勁。它常見于數(shù)據采集、內部服務探活、CI 里的小工具這類場景。裝不順的后果很直接編譯期缺頭鏈接期缺符號運行期 SSL 握手失敗一路踩下來比手寫 libcurl 還費時間。這篇記錄適合正在找 cpr-1.3.0 怎么安裝、怎么配置、環(huán)境怎么搭的人。2. 環(huán)境盤點cpr 1.3.0 編起來到底要哪幾樣東西動手之前先把依賴列清楚比編到一半再回頭補要省事得多。cpr 1.3.0 本身不復雜它就是一層薄封裝真正的重活在 libcurl 和 OpenSSL 上。麻煩的地方在于它的 CMake 腳本默認行為偏自給自足會嘗試自己去弄 curl 源碼這在有外網的開發(fā)機上無感在隔離環(huán)境里就是災難。所以這一章的重點不是羅列依賴而是把每個依賴的來源定下來編譯器從系統(tǒng)來curl 從系統(tǒng)來SSL 從系統(tǒng)來三樣都鎖死構建過程才是可復現(xiàn)的。2.1 編譯器與 C 標準C11 是底線不是可選項cpr 1.3.0 的公開頭文件里用了std::function、std::unordered_map、右值引用和大量 lambda編譯選項里必須打開 C11。GCC 建議 7 以上Clang 建議 6 以上MSVC 走 2017 以后的版本比較穩(wěn)。我一般不去賭默認標準而是在工程頂層直接寫死避免某個下游工程把-std覆蓋掉之后報出一堆看不懂的模板推導錯誤。# 頂層 CMakeLists.txt在 project() 之后立刻設置 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 找不到 C11 編譯器就直接失敗而不是悄悄降級 set(CMAKE_CXX_EXTENSIONS OFF) # 關掉 gnu11保持可移植這三行的邏輯是第一行聲明目標標準第二行把必須有變成硬約束第三行避免編譯期混入 GNU 擴展導致?lián)Q編譯器就編不過。很多在我機器上能編的事故源頭就是CMAKE_CXX_EXTENSIONS默認開著代碼里不小心用了typeof之類的東西換到 Clang 上直接崩。如果你的工程已經是 C14 或 C17不用降級cpr 1.3.0 在更高標準下也能編只是別把-stdc98這種老配置帶進來。2.2 libcurl 用系統(tǒng)的還是自帶的一個決定影響后面所有鏈接錯誤cpr 的 CMake 里有一個開關叫CPR_FORCE_USE_SYSTEM_CURL默認是關閉的。關閉狀態(tài)下構建腳本會嘗試把 curl 源碼弄到本地再一起編。這個設計對想零依賴的人友好但在實際部署里問題不少構建過程會依賴外部源碼獲取網絡受限時直接卡住就算拿到了源碼編出來的 curl 和系統(tǒng)里其他程序用的 curl 也是兩份后面做動態(tài)鏈接時符號容易打架。我的做法是一律強制用系統(tǒng) curl前提是先確認開發(fā)包裝好了# Debian / Ubuntu 系裝 curl 的開發(fā)頭文件和靜態(tài)庫 sudo apt-get install -y libcurl4-openssl-dev # RHEL / CentOS 系 sudo yum install -y libcurl-devel # 確認系統(tǒng)里的 curl 版本低于 7.50 建議先升級 curl-config --version curl-config --libs # 看鏈接參數(shù)里是否帶 -lssl -lcryptolibcurl4-openssl-dev這個名字不是隨便挑的它決定了 curl 背后用的是 OpenSSL 而不是別的 TLS 實現(xiàn)。cpr 的 SSL 相關代碼路徑和 curl 的 TLS 后端是綁定的混用會出現(xiàn)編譯通過但運行期證書校驗行為異常這種很難查的問題。curl-config --libs的輸出要重點看如果里面沒有-lssl -lcrypto說明裝的是不帶 SSL 的版本后面CPR_ENABLE_SSLON會直接失敗。裝完開發(fā)包后再跑一次curl-config --version把版本號記下來后面排查時有用。2.3 OpenSSL 與 zlibSSL 開關背后的兩個真實依賴cpr 1.3.0 的CPR_ENABLE_SSL默認打開打開之后就會去找 OpenSSL 的頭文件和庫。1.1.1 系列是目前兼容性最好的選擇如果系統(tǒng)里是 3.x多數(shù)情況下也能編但要留意 cpr 這層封裝里對舊宏的引用個別發(fā)行版會報OPENSSL_VERSION_NUMBER相關的棄用警告警告本身不影響產物但會淹沒真正的錯誤信息。zlib 的情況稍微特殊一點cpr 本身不直接用 zlib但 curl 在開啟內容壓縮支持時會依賴它。如果你的請求需要帶Accept-Encoding: gzip那 curl 編的時候就必須帶 zlib否則服務端返回壓縮體時你拿到的是亂碼。檢查辦法很直接# 看 curl 的編譯特性里有沒有 zlib 和 SSL curl -V # 輸出里的 Features 一行應包含 libz、SSL、HTTPS-proxy 等關鍵字這一步屬于裝之前花十秒裝之后省兩小時的檢查。很多環(huán)境里 curl 是精簡版編譯的特性列表里沒有 libz等到業(yè)務代碼里手動解壓失敗才發(fā)現(xiàn)回頭重裝 curl 還得連帶重編 cpr代價不小。2.4 一套我常用的版本組合下面這張表是我這幾年在不同機器上落地過的組合不是官方要求只是這個范圍內我沒翻過車的經驗區(qū)間。跨大版本時差異會放大比如把 curl 從 7.x 換到 8.x鏈接參數(shù)和部分宏定義都有變化需要重新驗證一遍。組件推薦區(qū)間說明CMake3.10 及以上低版本對target_include_directories的 install 導出支持不全GCC7 及以上低于 7 時 C11 的std::string_view替代實現(xiàn)容易出問題Clang6 及以上與 libstdc 搭配時注意版本匹配libcurl7.58 及以上7.58 前后 SSL 相關宏有調整1.3.0 在舊版上偶發(fā)編譯錯誤OpenSSL1.1.1 系列兼容性最好3.x 可用但會有棄用警告zlib1.2.8 及以上只影響壓縮傳輸不影響基礎請求這張表的意義在于縮小排查范圍。當你遇到一個詭異的編譯錯誤時先對照表格確認自己不在邊緣組合上再去翻代碼效率會高很多。3. 編譯安裝把 cpr 1.3.0 裝進一個干凈前綴到這一步依賴都齊了可以開始編。我強烈建議裝到獨立前綴而不是/usr/local原因很現(xiàn)實cpr 1.3.0 是幾年前的版本你手上可能還有別的工程依賴更高版本的 cpr全都塞進/usr/local之后find_package找到哪個全看運氣。獨立前綴加上CMAKE_PREFIX_PATH能把這套依賴隔離得干干凈凈卸載的時候一個rm -rf就完事不留殘渣。3.1 源碼落地與 out-of-source 構建目錄先建兩個目錄一個放源碼一個放構建產物嚴格分開。in-source 構建在 cpr 這種帶代碼生成的工程里尤其危險中間文件會污染源碼樹下次換配置時 CMakeCache 里全是臟數(shù)據。# 目錄規(guī)劃源碼和產物分開安裝前綴獨立 mkdir -p ~/work/cpr-1.3.0-src mkdir -p ~/work/build-cpr mkdir -p /opt/cpr-1.3.0 # 假設源碼包已經解壓到 ~/work/cpr-1.3.0-src cd ~/work/cpr-1.3.0-src ls CMakeLists.txt include/ # 確認目錄結構對得上再往下走ls這一步別省。有些壓縮包解開后多套一層目錄直接cmake -S .會報找不到 CMakeLists.txt新手容易在這里懷疑人生。確認CMakeLists.txt和include/在同一層就是正確的源碼根目錄。安裝前綴/opt/cpr-1.3.0里的版本號也別省將來并存多個版本時這個命名能救你一次。3.2 CMake 關鍵選項逐個拆配置階段是整個安裝過程里最值得花時間的地方。下面這條命令是我在大多數(shù)環(huán)境里用的版本參數(shù)看著多但每一項都對應一個具體的失敗場景。cmake -S ~/work/cpr-1.3.0-src \ -B ~/work/build-cpr \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/opt/cpr-1.3.0 \ -DCPR_BUILD_TESTSOFF \ -DCPR_BUILD_SERVEROFF \ -DCPR_ENABLE_SSLON \ -DCPR_FORCE_USE_SYSTEM_CURLON \ -DBUILD_SHARED_LIBSON \ -DCMAKE_POSITION_INDEPENDENT_CODEON逐項說明-S和-B是現(xiàn)代 CMake 的寫法分別指源碼目錄和構建目錄等價于進目錄再跑cmake ..但更不容易出錯。CMAKE_BUILD_TYPERelease打開優(yōu)化并去掉調試符號。cpr 1.3.0 在 Debug 下編出來的庫體積會大不少作為依賴庫沒必要。CMAKE_INSTALL_PREFIX決定make install往哪寫這里就是前面建好的獨立前綴。CPR_BUILD_TESTSOFF很關鍵。打開后它會去找測試框架在你沒有預裝的環(huán)境里會直接失敗而且測試代碼本身對產物沒有任何貢獻。CPR_BUILD_SERVEROFF關掉配套的測試服務端同理。CPR_ENABLE_SSLON顯式打開別依賴默認值尤其在別人寫好的構建腳本里。CPR_FORCE_USE_SYSTEM_CURLON是前面 2.2 節(jié)說過的那個決定必須顯式指定。BUILD_SHARED_LIBSON出動態(tài)庫。如果你的部署環(huán)境不方便帶.so改成OFF出靜態(tài)庫這個取舍在第 4 章細說。CMAKE_POSITION_INDEPENDENT_CODEON保證生成的庫能被鏈接進動態(tài)庫即使當前選的是靜態(tài)庫也建議開著。配置跑完后重點看輸出的末尾幾行會打印出檢測到的 curl 版本、SSL 后端、是否啟用 zlib。這三行信息比任何文檔都真實因為它是從當前這臺機器上探測出來的。3.3 編譯、安裝以及 generated 頭文件這一關cmake --build ~/work/build-cpr -j$(nproc) cmake --install ~/work/build-cpr-j后面跟并行度用nproc拿到核數(shù)就行。cpr 本身編譯很快瓶頸通常在它要不要額外編 curl一旦看到編譯過程里出現(xiàn)了大量 curl 的源文件說明 3.2 節(jié)那個開關沒生效回去檢查參數(shù)拼寫。安裝完之后必須做一次落地檢查這是整個流程里最容易被跳過、也最容易出問題的一步# 檢查關鍵頭文件和庫是否真的落到了前綴目錄 find /opt/cpr-1.3.0 -name *.h | head -20 find /opt/cpr-1.3.0 -name libcpr* ls /opt/cpr-1.3.0/lib/cmake/cpr/ 2/dev/null || echo 缺 CMake 配置文件三條命令分別查頭文件、庫文件、CMake 包配置。重點看頭文件列表里有沒有一個路徑里帶generated字樣的文件——cpr 1.3.0 在構建時會生成一份與 curl 頭文件版本相關的中間頭文件而老版本的安裝規(guī)則在某些平臺上不會把它一起裝進去于是出現(xiàn)第 1 章開頭那個報錯。如果確實缺了從構建目錄里找出來手動補進去# 在構建目錄里定位生成的中間頭文件 find ~/work/build-cpr -name cpr_generated_includes.h # 找到后按原相對路徑補到安裝前綴 mkdir -p /opt/cpr-1.3.0/include/cpr/generated cp ~/work/build-cpr/include/cpr/generated/cpr_generated_includes.h \ /opt/cpr-1.3.0/include/cpr/generated/補完之后再find一次確認。這一步屬于典型的官方安裝規(guī)則沒覆蓋到的坑不補的話下游工程#include cpr/cpr.h必然失敗而且報錯指向的是一個你沒寫過的文件名第一眼很難聯(lián)想到是安裝不完整。CMake 里還有個CPR_GENERATED_SOURCES_DIRECTORY變量可以用來指定生成物的輸出位置不同小版本行為不完全一致我最后都會用上面這條手動校驗兜底不賭它的默認行為。另外如果目標是直接拿現(xiàn)成的庫文件用那么落地檢查同樣適用頭文件樹里必須有cpr/cpr.h、cpr/generated/下那個生成文件、lib/下的庫以及l(fā)ib/cmake/cpr/下的配置文件四樣少一樣都不算完整。少 CMake 配置文件的后果是find_package直接失敗很多人在這一步誤以為是版本不匹配其實只是安裝不完整。3.4 find_package 接入與 pkg-config 備選安裝到位之后在下游工程里就該能直接找到了。標準寫法# 下游工程的 CMakeLists.txt find_package(cpr REQUIRED) add_executable(probe main.cpp) target_link_libraries(probe PRIVATE cpr::cpr)find_package會去CMAKE_PREFIX_PATH里找cprConfig.cmake所以如果裝在/opt下配置時要帶上路徑cmake -S . -B build -DCMAKE_PREFIX_PATH/opt/cpr-1.3.0如果find_package報找不到先別懷疑版本按順序查三件事配置文件是否在lib/cmake/cpr/下、CMAKE_PREFIX_PATH是否傳進去了、前置的 curl 是否也能被找到。第三條經常被忽略——cpr 的配置文件里會find_dependency(CURL)如果你把 cpr 裝到了前綴里但 curl 是系統(tǒng)包通常沒問題反過來把 curl 也裝在獨立前綴里卻忘了把那個前綴加進搜索路徑就會在find_package(cpr)這一行報出莫名其妙的依賴錯誤。target_link_libraries里的cpr::cpr是導出目標名。個別打包方式下目標名會不一樣鏈接時報 Target not found 的話打開cprConfig.cmake看一眼里面add_library(... IMPORTED)那行寫的是什么名字照著改即可別去改系統(tǒng)文件。對于不用 CMake 的老工程還有一條退路是直接手寫鏈接參數(shù)# 用 curl-config 拿 curl 的鏈接參數(shù)再拼上 cpr 的庫 g main.cpp -I/opt/cpr-1.3.0/include \ -L/opt/cpr-1.3.0/lib -lcpr \ $(curl-config --libs) -lssl -lcrypto -lz -o probe這條命令的每段都有用-I指向 cpr 頭文件-L -lcpr指向庫curl-config --libs把 curl 需要的參數(shù)一次性展開最后三個是 SSL 和壓縮的顯式依賴。順序很重要庫要放在源文件后面否則 GCC 會因為符號未解析而報錯。4. 工程接入把 cpr 1.3.0 寫進業(yè)務代碼庫裝好了只是開始真正決定這套環(huán)境好不好用的是接入方式。cpr 1.3.0 的 API 設計很接近腳本語言的 HTTP 客戶端幾行就能發(fā)請求但也正因為太順手容易寫出沒有超時、沒有錯誤分支、連接不復用的代碼上線之后在弱網環(huán)境里表現(xiàn)一塌糊涂。這一章從最小可運行例子往外擴把參數(shù)取舍講清楚。4.1 最小可編譯的 CMakeLists 與一次 GET先跑通再說別的。下面這段是能編能跑的最小骨架#include cpr/cpr.h #include iostream int main() { // 用本地地址驗證避免引入外部依賴 cpr::Response r cpr::Get( cpr::Url{http://127.0.0.1:8080/health}, cpr::Timeout{3000} // 整體超時單位毫秒 ); // error.code 是傳輸層狀態(tài)status_code 是 HTTP 層狀態(tài)兩者互不替代 if (r.error.code ! cpr::ErrorCode::OK) { std::cerr transport: r.error.message \n; return 2; } std::cout http r.status_code body r.text \n; return 0; }關鍵在最后那個判斷。cpr 把兩類失敗分得很清楚r.error記錄的是連接超時、DNS 失敗、SSL 握手失敗這類傳輸層問題r.status_code記錄的是服務端返回的 HTTP 狀態(tài)碼。只判斷status_code是新手最常見的疏漏——連接都失敗了status_code是 0業(yè)務邏輯會把它當成服務端返回 0處理后面全亂。判斷順序永遠是先看error.code再看status_code。配套的 CMakeLists 就是 3.4 節(jié)那幾行加上源文件即可。注意別在target_link_libraries里再手動補-lcurlcpr::cpr已經把傳遞依賴帶上了重復鏈接在某些平臺上會導致符號重復定義。4.2 超時、重試與 SSL 校驗的參數(shù)取舍生產代碼和 Demo 的差距基本都在這三個參數(shù)上。cpr 1.3.0 的超時是整體超時不是連接超時和讀取超時的分別設置所以給值的時候要按業(yè)務最壞情況考慮。#include cpr/cpr.h #include chrono #include thread #include iostream // 帶退避的簡單重試只對傳輸層失敗重試HTTP 4xx 不重試 cpr::Response GetWithRetry(const std::string url, int max_attempts 3) { cpr::Response r; for (int i 0; i max_attempts; i) { cpr::Session s; s.SetUrl(cpr::Url{url}); s.SetTimeout(cpr::Timeout{2000}); // 單次請求 2 秒 s.SetConnectTimeout(cpr::ConnectTimeout{800}); // 建連單獨限時 s.SetHeader(cpr::Header{{User-Agent, cpr-1.3.0-probe}}); r s.Get(); if (r.error.code cpr::ErrorCode::OK) { return r; // 傳輸成功就返回HTTP 層交給調用方判斷 } std::this_thread::sleep_for(std::chrono::milliseconds(200 * (i 1))); } return r; }這段的取舍點有三個。第一Timeout和ConnectTimeout分開設建連超時給得短一些能快速判斷目標是否可達整體超時留出讀取響應的時間。第二重試只針對傳輸層錯誤HTTP 500 這種服務端明確返回的結果不重試重試反而可能放大故障。第三退避用線性遞增簡單夠用不需要引入額外依賴。關于 SSL 校驗cpr 提供了cpr::VerifySsl{false}來跳過證書校驗。這個開關在調試自簽證書的內網服務時確實方便但絕對不要出現(xiàn)在生產代碼里。如果內網服務用的是自簽證書正確做法是把 CA 證書裝進系統(tǒng)信任庫或者用cpr::SslOptions指定 CA 路徑而不是關校驗。這條屬于血淚經驗跳過校驗的代碼一旦進了主干后面很難再摘出來。4.3 靜態(tài)鏈接與動態(tài)鏈接部署時的取舍裝的時候BUILD_SHARED_LIBS選哪個直接決定部署形態(tài)。動態(tài)庫的好處是多個程序共用一份libcpr.so升級時替換文件即可缺點是部署時必須帶上.so還得處理RPATH或者設LD_LIBRARY_PATH。cpr 依賴 curlcurl 又依賴 SSL 和 zlib動態(tài)鏈接下這條依賴鏈上任何一環(huán)版本不匹配運行期就是一個symbol lookup error。靜態(tài)庫的好處是產物自包含拷貝一個可執(zhí)行文件就能跑特別適合分發(fā)小工具或者塞進容器鏡像。代價是體積變大而且必須確保 curl 的靜態(tài)庫也在系統(tǒng)里——很多發(fā)行版的libcurl4-openssl-dev只帶動態(tài)庫靜態(tài)庫在單獨的包里裝漏了會在鏈接階段報找不到libcurl.a。我的習慣是內部服務用動態(tài)庫方便統(tǒng)一升級對外分發(fā)的小工具用靜態(tài)庫減少環(huán)境依賴。如果選靜態(tài)安裝 cpr 時把BUILD_SHARED_LIBS設為OFF下游鏈接時確保-lcurl -lssl -lcrypto -lz都能找到靜態(tài)版本。4.4 復用 Session 而不是每次新建cpr 的cpr::Get這種自由函數(shù)寫法內部會新建一個 Session用完銷毀連接自然也不復用。在請求量大的場景里這會明顯拖慢吞吐。改成顯式持有 Session// 長生命周期的 Session復用連接和 TLS 會話 cpr::Session session; session.SetUrl(cpr::Url{http://127.0.0.1:8080/api/items}); session.SetTimeout(cpr::Timeout{2000}); session.SetHeader(cpr::Header{{Accept, application/json}}); // 同一個 Session 可以改參數(shù)后重復調用 session.SetParameters(cpr::Parameters{{page, 1}, {size, 50}}); cpr::Response first session.Get(); session.SetParameters(cpr::Parameters{{page, 2}, {size, 50}}); cpr::Response second session.Get();要注意 Session 不是線程安全的一個實例只能在一個線程里用。多線程場景下每個線程各自持有 Session別圖省事搞個全局共享的那種問題往往在高并發(fā)壓測時才暴露排查成本很高。5. 常見排查cpr 1.3.0 編譯鏈接的五個翻車現(xiàn)場這一章按現(xiàn)象 → 原因 → 解決記錄五條實際遇到過的故障。它們的共同點是報錯信息都不太直觀第一眼容易往錯誤的方向猜。5.1 編譯期三類報錯第一條報fatal error: cpr/generated/cpr_generated_includes.h: No such file or directory。現(xiàn)象是庫裝了、頭文件路徑也加了就是缺這一個文件。原因是 1.3.0 的安裝規(guī)則沒有把這個構建時生成的頭文件一起裝進去具體表現(xiàn)隨平臺和 CMake 版本略有差異。解決就是 3.3 節(jié)那套從構建目錄find出來按相對路徑手動補到$PREFIX/include/cpr/generated/下補完記得再find一次確認。第二條報大量undefined reference to curl_easy_...?，F(xiàn)象是編譯通過鏈接階段成片報錯。原因是鏈接順序不對或者cpr::cpr的傳遞依賴沒生效。解決是先確認用的是target_link_libraries(xxx PRIVATE cpr::cpr)而不是手寫-lcpr手寫的話庫必須放在目標文件之后并且補上$(curl-config --libs)。如果還是不行檢查是不是同時鏈接了系統(tǒng)里另一份 curl。第三條配置階段卡住或者報下載失敗?，F(xiàn)象是cmake跑到一半長時間沒動靜日志里出現(xiàn)獲取外部源碼的動作。原因就是CPR_FORCE_USE_SYSTEM_CURL沒開腳本在嘗試自己弄 curl。解決是回到 3.2 節(jié)把這個參數(shù)顯式設為ON然后刪掉構建目錄重新配置——注意是刪掉整個構建目錄只改參數(shù)重跑緩存的變量未必能覆蓋干凈。5.2 鏈接與運行期兩類報錯第四條運行期報 SSL 相關錯誤r.error.message里出現(xiàn)證書驗證失敗的字樣?，F(xiàn)象是請求某個 HTTPS 地址一直失敗換 HTTP 就正常。原因是 curl 編譯時用的 TLS 后端和系統(tǒng)信任庫路徑對不上或者時間不對導致證書被判定為未生效。解決是先跑curl -V確認 Features 里有 SSL再用curl -v https://目標地址對照排查——如果命令行 curl 也失敗問題在系統(tǒng)層跟 cpr 無關如果命令行成功而 cpr 失敗檢查鏈接的是不是另一份 curl。第五條程序啟動就報找不到libcpr.so?，F(xiàn)象是編譯鏈接都通過了執(zhí)行時報共享庫加載失敗。原因是庫裝在非標準前綴運行時加載器找不到。解決有三個層次臨時用LD_LIBRARY_PATH/opt/cpr-1.3.0/lib ./probe驗證確認是路徑問題長期方案是在 CMake 里設置INSTALL_RPATH或者把前綴寫進/etc/ld.so.conf.d/后跑一次ldconfig。千萬別把LD_LIBRARY_PATH寫進全局 shell 配置文件那會影響同一臺機器上所有程序后患無窮。6. 驗證跑通三組對照把能跑和跑對分開裝完最忌諱的是編譯通過就完事。我見過太多次編譯沒問題、一上真實網絡就出狀況的情況。下面這套驗證分三層一層比一層接近真實使用。第一層靜態(tài)檢查。確認四樣東西齊全檢查項路徑缺失后果主頭文件/opt/cpr-1.3.0/include/cpr/cpr.h編譯直接失敗生成頭文件/opt/cpr-1.3.0/include/cpr/generated/cpr_generated_includes.h編譯報找不到文件庫文件/opt/cpr-1.3.0/lib/libcpr.so或.a鏈接失敗CMake 配置/opt/cpr-1.3.0/lib/cmake/cpr/cprConfig.cmakefind_package失敗第二層本地回環(huán)驗證。用一個本地起的小服務返回固定 JSON跑第 4 章那個最小例子確認status_code是 200、r.text內容正確、r.error.code是OK。這一步排除網絡因素驗證的是庫鏈接正確、請求能發(fā)出去。同時故意請求一個不存在的端口確認r.error.code不是OK且程序走的是錯誤分支——錯誤分支沒被驗證過等于沒寫。第三層真實環(huán)境驗證。挑一個內網的 HTTPS 接口用 Session 復用方式連發(fā)十次觀察兩件事十次全部成功說明連接復用和 TLS 會話沒出問題r.elapsed從第二次開始明顯下降說明連接確實被復用了。如果十次耗時一樣說明每次都在重新建連回去檢查是不是不小心每次都新建了 Session。最后給個習慣。從那以后我每次裝完 cpr都會把這三層驗證做成一個verify.sh留在構建目錄里包含路徑檢查、本地回環(huán)請求、十次連發(fā)計時三段。原因很簡單這套依賴橫跨編譯器、curl、SSL 三層任何一層動過表現(xiàn)都可能變化而人腦記不住上次驗證時的細節(jié)。腳本跑一遍輸出的三行結果就是這份環(huán)境還能不能用的黑匣子記錄比回憶靠譜得多。裝環(huán)境這事沒有一勞永逸只有每次都走一遍的后悔藥。希望幫到你。本文還有配套的精品資源點擊獲取 cpr 1.3.0 編譯安裝與工程接入避坑指南
簡介cpr-1.3.0 預編譯庫面向使用 C 發(fā)起 HTTP 請求的開發(fā)者適合在 VS 項目中快速接入、又不想自行編譯 cpr 與 libcurl 的初、中級人員。壓縮包共 27 個文件含 21 個頭文件、4 個 lib 靜態(tài)庫和 2 個 dll 動態(tài)庫Debug/Release 均提供 cpr.lib、libcurl.dll 等整體約 738KB便于隨工程歸檔引用。資源由 weststarqp 于 2019 年 2 月基于 VS2015 編譯已有 691 人學習。解壓后可按配置將頭文件、庫文件與動態(tài)庫加入工程減少搭建依賴環(huán)境的時間并借助頭文件了解 session、response、auth、cookies 等接口為請求封裝和調試提供基礎。1. 從一次庫在頭文件不在的編譯失敗說起上周接手一個內部工具的構建CMakeLists 里一行find_package(cpr REQUIRED)我以為是十分鐘的事結果make直接甩出一堆fatal error: cpr/generated/cpr_generated_includes.h: No such file or directory。庫文件明明裝了頭文件目錄也加進-I了偏偏缺一個名字很長的中間頭文件。這就是 cpr 1.3.0 最經典的一關。cpr 全稱 C Requests是把 libcurl 那套 C 接口包成cpr::Get/cpr::Response風格的 C11 庫寫 HTTP 客戶端時不用再和curl_easy_setopt的變參列表較勁。它常見于數(shù)據采集、內部服務探活、CI 里的小工具這類場景。裝不順的后果很直接編譯期缺頭鏈接期缺符號運行期 SSL 握手失敗一路踩下來比手寫 libcurl 還費時間。這篇記錄適合正在找 cpr-1.3.0 怎么安裝、怎么配置、環(huán)境怎么搭的人。2. 環(huán)境盤點cpr 1.3.0 編起來到底要哪幾樣東西動手之前先把依賴列清楚比編到一半再回頭補要省事得多。cpr 1.3.0 本身不復雜它就是一層薄封裝真正的重活在 libcurl 和 OpenSSL 上。麻煩的地方在于它的 CMake 腳本默認行為偏自給自足會嘗試自己去弄 curl 源碼這在有外網的開發(fā)機上無感在隔離環(huán)境里就是災難。所以這一章的重點不是羅列依賴而是把每個依賴的來源定下來編譯器從系統(tǒng)來curl 從系統(tǒng)來SSL 從系統(tǒng)來三樣都鎖死構建過程才是可復現(xiàn)的。2.1 編譯器與 C 標準C11 是底線不是可選項cpr 1.3.0 的公開頭文件里用了std::function、std::unordered_map、右值引用和大量 lambda編譯選項里必須打開 C11。GCC 建議 7 以上Clang 建議 6 以上MSVC 走 2017 以后的版本比較穩(wěn)。我一般不去賭默認標準而是在工程頂層直接寫死避免某個下游工程把-std覆蓋掉之后報出一堆看不懂的模板推導錯誤。# 頂層 CMakeLists.txt在 project() 之后立刻設置 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 找不到 C11 編譯器就直接失敗而不是悄悄降級 set(CMAKE_CXX_EXTENSIONS OFF) # 關掉 gnu11保持可移植這三行的邏輯是第一行聲明目標標準第二行把必須有變成硬約束第三行避免編譯期混入 GNU 擴展導致?lián)Q編譯器就編不過。很多在我機器上能編的事故源頭就是CMAKE_CXX_EXTENSIONS默認開著代碼里不小心用了typeof之類的東西換到 Clang 上直接崩。如果你的工程已經是 C14 或 C17不用降級cpr 1.3.0 在更高標準下也能編只是別把-stdc98這種老配置帶進來。2.2 libcurl 用系統(tǒng)的還是自帶的一個決定影響后面所有鏈接錯誤cpr 的 CMake 里有一個開關叫CPR_FORCE_USE_SYSTEM_CURL默認是關閉的。關閉狀態(tài)下構建腳本會嘗試把 curl 源碼弄到本地再一起編。這個設計對想零依賴的人友好但在實際部署里問題不少構建過程會依賴外部源碼獲取網絡受限時直接卡住就算拿到了源碼編出來的 curl 和系統(tǒng)里其他程序用的 curl 也是兩份后面做動態(tài)鏈接時符號容易打架。我的做法是一律強制用系統(tǒng) curl前提是先確認開發(fā)包裝好了# Debian / Ubuntu 系裝 curl 的開發(fā)頭文件和靜態(tài)庫 sudo apt-get install -y libcurl4-openssl-dev # RHEL / CentOS 系 sudo yum install -y libcurl-devel # 確認系統(tǒng)里的 curl 版本低于 7.50 建議先升級 curl-config --version curl-config --libs # 看鏈接參數(shù)里是否帶 -lssl -lcryptolibcurl4-openssl-dev這個名字不是隨便挑的它決定了 curl 背后用的是 OpenSSL 而不是別的 TLS 實現(xiàn)。cpr 的 SSL 相關代碼路徑和 curl 的 TLS 后端是綁定的混用會出現(xiàn)編譯通過但運行期證書校驗行為異常這種很難查的問題。curl-config --libs的輸出要重點看如果里面沒有-lssl -lcrypto說明裝的是不帶 SSL 的版本后面CPR_ENABLE_SSLON會直接失敗。裝完開發(fā)包后再跑一次curl-config --version把版本號記下來后面排查時有用。2.3 OpenSSL 與 zlibSSL 開關背后的兩個真實依賴cpr 1.3.0 的CPR_ENABLE_SSL默認打開打開之后就會去找 OpenSSL 的頭文件和庫。1.1.1 系列是目前兼容性最好的選擇如果系統(tǒng)里是 3.x多數(shù)情況下也能編但要留意 cpr 這層封裝里對舊宏的引用個別發(fā)行版會報OPENSSL_VERSION_NUMBER相關的棄用警告警告本身不影響產物但會淹沒真正的錯誤信息。zlib 的情況稍微特殊一點cpr 本身不直接用 zlib但 curl 在開啟內容壓縮支持時會依賴它。如果你的請求需要帶Accept-Encoding: gzip那 curl 編的時候就必須帶 zlib否則服務端返回壓縮體時你拿到的是亂碼。檢查辦法很直接# 看 curl 的編譯特性里有沒有 zlib 和 SSL curl -V # 輸出里的 Features 一行應包含 libz、SSL、HTTPS-proxy 等關鍵字這一步屬于裝之前花十秒裝之后省兩小時的檢查。很多環(huán)境里 curl 是精簡版編譯的特性列表里沒有 libz等到業(yè)務代碼里手動解壓失敗才發(fā)現(xiàn)回頭重裝 curl 還得連帶重編 cpr代價不小。2.4 一套我常用的版本組合下面這張表是我這幾年在不同機器上落地過的組合不是官方要求只是這個范圍內我沒翻過車的經驗區(qū)間。跨大版本時差異會放大比如把 curl 從 7.x 換到 8.x鏈接參數(shù)和部分宏定義都有變化需要重新驗證一遍。組件推薦區(qū)間說明CMake3.10 及以上低版本對target_include_directories的 install 導出支持不全GCC7 及以上低于 7 時 C11 的std::string_view替代實現(xiàn)容易出問題Clang6 及以上與 libstdc 搭配時注意版本匹配libcurl7.58 及以上7.58 前后 SSL 相關宏有調整1.3.0 在舊版上偶發(fā)編譯錯誤OpenSSL1.1.1 系列兼容性最好3.x 可用但會有棄用警告zlib1.2.8 及以上只影響壓縮傳輸不影響基礎請求這張表的意義在于縮小排查范圍。當你遇到一個詭異的編譯錯誤時先對照表格確認自己不在邊緣組合上再去翻代碼效率會高很多。3. 編譯安裝把 cpr 1.3.0 裝進一個干凈前綴到這一步依賴都齊了可以開始編。我強烈建議裝到獨立前綴而不是/usr/local原因很現(xiàn)實cpr 1.3.0 是幾年前的版本你手上可能還有別的工程依賴更高版本的 cpr全都塞進/usr/local之后find_package找到哪個全看運氣。獨立前綴加上CMAKE_PREFIX_PATH能把這套依賴隔離得干干凈凈卸載的時候一個rm -rf就完事不留殘渣。3.1 源碼落地與 out-of-source 構建目錄先建兩個目錄一個放源碼一個放構建產物嚴格分開。in-source 構建在 cpr 這種帶代碼生成的工程里尤其危險中間文件會污染源碼樹下次換配置時 CMakeCache 里全是臟數(shù)據。# 目錄規(guī)劃源碼和產物分開安裝前綴獨立 mkdir -p ~/work/cpr-1.3.0-src mkdir -p ~/work/build-cpr mkdir -p /opt/cpr-1.3.0 # 假設源碼包已經解壓到 ~/work/cpr-1.3.0-src cd ~/work/cpr-1.3.0-src ls CMakeLists.txt include/ # 確認目錄結構對得上再往下走ls這一步別省。有些壓縮包解開后多套一層目錄直接cmake -S .會報找不到 CMakeLists.txt新手容易在這里懷疑人生。確認CMakeLists.txt和include/在同一層就是正確的源碼根目錄。安裝前綴/opt/cpr-1.3.0里的版本號也別省將來并存多個版本時這個命名能救你一次。3.2 CMake 關鍵選項逐個拆配置階段是整個安裝過程里最值得花時間的地方。下面這條命令是我在大多數(shù)環(huán)境里用的版本參數(shù)看著多但每一項都對應一個具體的失敗場景。cmake -S ~/work/cpr-1.3.0-src \ -B ~/work/build-cpr \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/opt/cpr-1.3.0 \ -DCPR_BUILD_TESTSOFF \ -DCPR_BUILD_SERVEROFF \ -DCPR_ENABLE_SSLON \ -DCPR_FORCE_USE_SYSTEM_CURLON \ -DBUILD_SHARED_LIBSON \ -DCMAKE_POSITION_INDEPENDENT_CODEON逐項說明-S和-B是現(xiàn)代 CMake 的寫法分別指源碼目錄和構建目錄等價于進目錄再跑cmake ..但更不容易出錯。CMAKE_BUILD_TYPERelease打開優(yōu)化并去掉調試符號。cpr 1.3.0 在 Debug 下編出來的庫體積會大不少作為依賴庫沒必要。CMAKE_INSTALL_PREFIX決定make install往哪寫這里就是前面建好的獨立前綴。CPR_BUILD_TESTSOFF很關鍵。打開后它會去找測試框架在你沒有預裝的環(huán)境里會直接失敗而且測試代碼本身對產物沒有任何貢獻。CPR_BUILD_SERVEROFF關掉配套的測試服務端同理。CPR_ENABLE_SSLON顯式打開別依賴默認值尤其在別人寫好的構建腳本里。CPR_FORCE_USE_SYSTEM_CURLON是前面 2.2 節(jié)說過的那個決定必須顯式指定。BUILD_SHARED_LIBSON出動態(tài)庫。如果你的部署環(huán)境不方便帶.so改成OFF出靜態(tài)庫這個取舍在第 4 章細說。CMAKE_POSITION_INDEPENDENT_CODEON保證生成的庫能被鏈接進動態(tài)庫即使當前選的是靜態(tài)庫也建議開著。配置跑完后重點看輸出的末尾幾行會打印出檢測到的 curl 版本、SSL 后端、是否啟用 zlib。這三行信息比任何文檔都真實因為它是從當前這臺機器上探測出來的。3.3 編譯、安裝以及 generated 頭文件這一關cmake --build ~/work/build-cpr -j$(nproc) cmake --install ~/work/build-cpr-j后面跟并行度用nproc拿到核數(shù)就行。cpr 本身編譯很快瓶頸通常在它要不要額外編 curl一旦看到編譯過程里出現(xiàn)了大量 curl 的源文件說明 3.2 節(jié)那個開關沒生效回去檢查參數(shù)拼寫。安裝完之后必須做一次落地檢查這是整個流程里最容易被跳過、也最容易出問題的一步# 檢查關鍵頭文件和庫是否真的落到了前綴目錄 find /opt/cpr-1.3.0 -name *.h | head -20 find /opt/cpr-1.3.0 -name libcpr* ls /opt/cpr-1.3.0/lib/cmake/cpr/ 2/dev/null || echo 缺 CMake 配置文件三條命令分別查頭文件、庫文件、CMake 包配置。重點看頭文件列表里有沒有一個路徑里帶generated字樣的文件——cpr 1.3.0 在構建時會生成一份與 curl 頭文件版本相關的中間頭文件而老版本的安裝規(guī)則在某些平臺上不會把它一起裝進去于是出現(xiàn)第 1 章開頭那個報錯。如果確實缺了從構建目錄里找出來手動補進去# 在構建目錄里定位生成的中間頭文件 find ~/work/build-cpr -name cpr_generated_includes.h # 找到后按原相對路徑補到安裝前綴 mkdir -p /opt/cpr-1.3.0/include/cpr/generated cp ~/work/build-cpr/include/cpr/generated/cpr_generated_includes.h \ /opt/cpr-1.3.0/include/cpr/generated/補完之后再find一次確認。這一步屬于典型的官方安裝規(guī)則沒覆蓋到的坑不補的話下游工程#include cpr/cpr.h必然失敗而且報錯指向的是一個你沒寫過的文件名第一眼很難聯(lián)想到是安裝不完整。CMake 里還有個CPR_GENERATED_SOURCES_DIRECTORY變量可以用來指定生成物的輸出位置不同小版本行為不完全一致我最后都會用上面這條手動校驗兜底不賭它的默認行為。另外如果目標是直接拿現(xiàn)成的庫文件用那么落地檢查同樣適用頭文件樹里必須有cpr/cpr.h、cpr/generated/下那個生成文件、lib/下的庫以及l(fā)ib/cmake/cpr/下的配置文件四樣少一樣都不算完整。少 CMake 配置文件的后果是find_package直接失敗很多人在這一步誤以為是版本不匹配其實只是安裝不完整。3.4 find_package 接入與 pkg-config 備選安裝到位之后在下游工程里就該能直接找到了。標準寫法# 下游工程的 CMakeLists.txt find_package(cpr REQUIRED) add_executable(probe main.cpp) target_link_libraries(probe PRIVATE cpr::cpr)find_package會去CMAKE_PREFIX_PATH里找cprConfig.cmake所以如果裝在/opt下配置時要帶上路徑cmake -S . -B build -DCMAKE_PREFIX_PATH/opt/cpr-1.3.0如果find_package報找不到先別懷疑版本按順序查三件事配置文件是否在lib/cmake/cpr/下、CMAKE_PREFIX_PATH是否傳進去了、前置的 curl 是否也能被找到。第三條經常被忽略——cpr 的配置文件里會find_dependency(CURL)如果你把 cpr 裝到了前綴里但 curl 是系統(tǒng)包通常沒問題反過來把 curl 也裝在獨立前綴里卻忘了把那個前綴加進搜索路徑就會在find_package(cpr)這一行報出莫名其妙的依賴錯誤。target_link_libraries里的cpr::cpr是導出目標名。個別打包方式下目標名會不一樣鏈接時報 Target not found 的話打開cprConfig.cmake看一眼里面add_library(... IMPORTED)那行寫的是什么名字照著改即可別去改系統(tǒng)文件。對于不用 CMake 的老工程還有一條退路是直接手寫鏈接參數(shù)# 用 curl-config 拿 curl 的鏈接參數(shù)再拼上 cpr 的庫 g main.cpp -I/opt/cpr-1.3.0/include \ -L/opt/cpr-1.3.0/lib -lcpr \ $(curl-config --libs) -lssl -lcrypto -lz -o probe這條命令的每段都有用-I指向 cpr 頭文件-L -lcpr指向庫curl-config --libs把 curl 需要的參數(shù)一次性展開最后三個是 SSL 和壓縮的顯式依賴。順序很重要庫要放在源文件后面否則 GCC 會因為符號未解析而報錯。4. 工程接入把 cpr 1.3.0 寫進業(yè)務代碼庫裝好了只是開始真正決定這套環(huán)境好不好用的是接入方式。cpr 1.3.0 的 API 設計很接近腳本語言的 HTTP 客戶端幾行就能發(fā)請求但也正因為太順手容易寫出沒有超時、沒有錯誤分支、連接不復用的代碼上線之后在弱網環(huán)境里表現(xiàn)一塌糊涂。這一章從最小可運行例子往外擴把參數(shù)取舍講清楚。4.1 最小可編譯的 CMakeLists 與一次 GET先跑通再說別的。下面這段是能編能跑的最小骨架#include cpr/cpr.h #include iostream int main() { // 用本地地址驗證避免引入外部依賴 cpr::Response r cpr::Get( cpr::Url{http://127.0.0.1:8080/health}, cpr::Timeout{3000} // 整體超時單位毫秒 ); // error.code 是傳輸層狀態(tài)status_code 是 HTTP 層狀態(tài)兩者互不替代 if (r.error.code ! cpr::ErrorCode::OK) { std::cerr transport: r.error.message \n; return 2; } std::cout http r.status_code body r.text \n; return 0; }關鍵在最后那個判斷。cpr 把兩類失敗分得很清楚r.error記錄的是連接超時、DNS 失敗、SSL 握手失敗這類傳輸層問題r.status_code記錄的是服務端返回的 HTTP 狀態(tài)碼。只判斷status_code是新手最常見的疏漏——連接都失敗了status_code是 0業(yè)務邏輯會把它當成服務端返回 0處理后面全亂。判斷順序永遠是先看error.code再看status_code。配套的 CMakeLists 就是 3.4 節(jié)那幾行加上源文件即可。注意別在target_link_libraries里再手動補-lcurlcpr::cpr已經把傳遞依賴帶上了重復鏈接在某些平臺上會導致符號重復定義。4.2 超時、重試與 SSL 校驗的參數(shù)取舍生產代碼和 Demo 的差距基本都在這三個參數(shù)上。cpr 1.3.0 的超時是整體超時不是連接超時和讀取超時的分別設置所以給值的時候要按業(yè)務最壞情況考慮。#include cpr/cpr.h #include chrono #include thread #include iostream // 帶退避的簡單重試只對傳輸層失敗重試HTTP 4xx 不重試 cpr::Response GetWithRetry(const std::string url, int max_attempts 3) { cpr::Response r; for (int i 0; i max_attempts; i) { cpr::Session s; s.SetUrl(cpr::Url{url}); s.SetTimeout(cpr::Timeout{2000}); // 單次請求 2 秒 s.SetConnectTimeout(cpr::ConnectTimeout{800}); // 建連單獨限時 s.SetHeader(cpr::Header{{User-Agent, cpr-1.3.0-probe}}); r s.Get(); if (r.error.code cpr::ErrorCode::OK) { return r; // 傳輸成功就返回HTTP 層交給調用方判斷 } std::this_thread::sleep_for(std::chrono::milliseconds(200 * (i 1))); } return r; }這段的取舍點有三個。第一Timeout和ConnectTimeout分開設建連超時給得短一些能快速判斷目標是否可達整體超時留出讀取響應的時間。第二重試只針對傳輸層錯誤HTTP 500 這種服務端明確返回的結果不重試重試反而可能放大故障。第三退避用線性遞增簡單夠用不需要引入額外依賴。關于 SSL 校驗cpr 提供了cpr::VerifySsl{false}來跳過證書校驗。這個開關在調試自簽證書的內網服務時確實方便但絕對不要出現(xiàn)在生產代碼里。如果內網服務用的是自簽證書正確做法是把 CA 證書裝進系統(tǒng)信任庫或者用cpr::SslOptions指定 CA 路徑而不是關校驗。這條屬于血淚經驗跳過校驗的代碼一旦進了主干后面很難再摘出來。4.3 靜態(tài)鏈接與動態(tài)鏈接部署時的取舍裝的時候BUILD_SHARED_LIBS選哪個直接決定部署形態(tài)。動態(tài)庫的好處是多個程序共用一份libcpr.so升級時替換文件即可缺點是部署時必須帶上.so還得處理RPATH或者設LD_LIBRARY_PATH。cpr 依賴 curlcurl 又依賴 SSL 和 zlib動態(tài)鏈接下這條依賴鏈上任何一環(huán)版本不匹配運行期就是一個symbol lookup error。靜態(tài)庫的好處是產物自包含拷貝一個可執(zhí)行文件就能跑特別適合分發(fā)小工具或者塞進容器鏡像。代價是體積變大而且必須確保 curl 的靜態(tài)庫也在系統(tǒng)里——很多發(fā)行版的libcurl4-openssl-dev只帶動態(tài)庫靜態(tài)庫在單獨的包里裝漏了會在鏈接階段報找不到libcurl.a。我的習慣是內部服務用動態(tài)庫方便統(tǒng)一升級對外分發(fā)的小工具用靜態(tài)庫減少環(huán)境依賴。如果選靜態(tài)安裝 cpr 時把BUILD_SHARED_LIBS設為OFF下游鏈接時確保-lcurl -lssl -lcrypto -lz都能找到靜態(tài)版本。4.4 復用 Session 而不是每次新建cpr 的cpr::Get這種自由函數(shù)寫法內部會新建一個 Session用完銷毀連接自然也不復用。在請求量大的場景里這會明顯拖慢吞吐。改成顯式持有 Session// 長生命周期的 Session復用連接和 TLS 會話 cpr::Session session; session.SetUrl(cpr::Url{http://127.0.0.1:8080/api/items}); session.SetTimeout(cpr::Timeout{2000}); session.SetHeader(cpr::Header{{Accept, application/json}}); // 同一個 Session 可以改參數(shù)后重復調用 session.SetParameters(cpr::Parameters{{page, 1}, {size, 50}}); cpr::Response first session.Get(); session.SetParameters(cpr::Parameters{{page, 2}, {size, 50}}); cpr::Response second session.Get();要注意 Session 不是線程安全的一個實例只能在一個線程里用。多線程場景下每個線程各自持有 Session別圖省事搞個全局共享的那種問題往往在高并發(fā)壓測時才暴露排查成本很高。5. 常見排查cpr 1.3.0 編譯鏈接的五個翻車現(xiàn)場這一章按現(xiàn)象 → 原因 → 解決記錄五條實際遇到過的故障。它們的共同點是報錯信息都不太直觀第一眼容易往錯誤的方向猜。5.1 編譯期三類報錯第一條報fatal error: cpr/generated/cpr_generated_includes.h: No such file or directory。現(xiàn)象是庫裝了、頭文件路徑也加了就是缺這一個文件。原因是 1.3.0 的安裝規(guī)則沒有把這個構建時生成的頭文件一起裝進去具體表現(xiàn)隨平臺和 CMake 版本略有差異。解決就是 3.3 節(jié)那套從構建目錄find出來按相對路徑手動補到$PREFIX/include/cpr/generated/下補完記得再find一次確認。第二條報大量undefined reference to curl_easy_...?，F(xiàn)象是編譯通過鏈接階段成片報錯。原因是鏈接順序不對或者cpr::cpr的傳遞依賴沒生效。解決是先確認用的是target_link_libraries(xxx PRIVATE cpr::cpr)而不是手寫-lcpr手寫的話庫必須放在目標文件之后并且補上$(curl-config --libs)。如果還是不行檢查是不是同時鏈接了系統(tǒng)里另一份 curl。第三條配置階段卡住或者報下載失敗?，F(xiàn)象是cmake跑到一半長時間沒動靜日志里出現(xiàn)獲取外部源碼的動作。原因就是CPR_FORCE_USE_SYSTEM_CURL沒開腳本在嘗試自己弄 curl。解決是回到 3.2 節(jié)把這個參數(shù)顯式設為ON然后刪掉構建目錄重新配置——注意是刪掉整個構建目錄只改參數(shù)重跑緩存的變量未必能覆蓋干凈。5.2 鏈接與運行期兩類報錯第四條運行期報 SSL 相關錯誤r.error.message里出現(xiàn)證書驗證失敗的字樣?，F(xiàn)象是請求某個 HTTPS 地址一直失敗換 HTTP 就正常。原因是 curl 編譯時用的 TLS 后端和系統(tǒng)信任庫路徑對不上或者時間不對導致證書被判定為未生效。解決是先跑curl -V確認 Features 里有 SSL再用curl -v https://目標地址對照排查——如果命令行 curl 也失敗問題在系統(tǒng)層跟 cpr 無關如果命令行成功而 cpr 失敗檢查鏈接的是不是另一份 curl。第五條程序啟動就報找不到libcpr.so?，F(xiàn)象是編譯鏈接都通過了執(zhí)行時報共享庫加載失敗。原因是庫裝在非標準前綴運行時加載器找不到。解決有三個層次臨時用LD_LIBRARY_PATH/opt/cpr-1.3.0/lib ./probe驗證確認是路徑問題長期方案是在 CMake 里設置INSTALL_RPATH或者把前綴寫進/etc/ld.so.conf.d/后跑一次ldconfig。千萬別把LD_LIBRARY_PATH寫進全局 shell 配置文件那會影響同一臺機器上所有程序后患無窮。6. 驗證跑通三組對照把能跑和跑對分開裝完最忌諱的是編譯通過就完事。我見過太多次編譯沒問題、一上真實網絡就出狀況的情況。下面這套驗證分三層一層比一層接近真實使用。第一層靜態(tài)檢查。確認四樣東西齊全檢查項路徑缺失后果主頭文件/opt/cpr-1.3.0/include/cpr/cpr.h編譯直接失敗生成頭文件/opt/cpr-1.3.0/include/cpr/generated/cpr_generated_includes.h編譯報找不到文件庫文件/opt/cpr-1.3.0/lib/libcpr.so或.a鏈接失敗CMake 配置/opt/cpr-1.3.0/lib/cmake/cpr/cprConfig.cmakefind_package失敗第二層本地回環(huán)驗證。用一個本地起的小服務返回固定 JSON跑第 4 章那個最小例子確認status_code是 200、r.text內容正確、r.error.code是OK。這一步排除網絡因素驗證的是庫鏈接正確、請求能發(fā)出去。同時故意請求一個不存在的端口確認r.error.code不是OK且程序走的是錯誤分支——錯誤分支沒被驗證過等于沒寫。第三層真實環(huán)境驗證。挑一個內網的 HTTPS 接口用 Session 復用方式連發(fā)十次觀察兩件事十次全部成功說明連接復用和 TLS 會話沒出問題r.elapsed從第二次開始明顯下降說明連接確實被復用了。如果十次耗時一樣說明每次都在重新建連回去檢查是不是不小心每次都新建了 Session。最后給個習慣。從那以后我每次裝完 cpr都會把這三層驗證做成一個verify.sh留在構建目錄里包含路徑檢查、本地回環(huán)請求、十次連發(fā)計時三段。原因很簡單這套依賴橫跨編譯器、curl、SSL 三層任何一層動過表現(xiàn)都可能變化而人腦記不住上次驗證時的細節(jié)。腳本跑一遍輸出的三行結果就是這份環(huán)境還能不能用的黑匣子記錄比回憶靠譜得多。裝環(huán)境這事沒有一勞永逸只有每次都走一遍的后悔藥。希望幫到你。本文還有配套的精品資源點擊獲取