Libcurl 完整指南：安裝、配置、常用 API 與七大實戰範例

Libcurl 完整指南：安裝、配置、常用 API 與七大實戰範例

Libcurl 是功能強大、跨平台、支援多種協定（HTTP/HTTPS/FTP/FTPS/TFTP/TELNET/DICT/LDAP/FILE）的客戶端 URL 傳輸庫，執行緒安全、支援 IPv6，廣泛用於 C/C++ 網路應用開發。

一、編譯安裝

wget https://curl.haxx.se/download/curl-7.39.0.tar.gz
tar -xzvf curl-7.39.0.tar.gz
cd curl-7.39.0
yum install gcc gcc-c++ openssl-devel
./configure --with-ssl
make
make install

安裝後可用 curl-config --libs --cflags 取得編譯連結參數。

二、核心 API 快速查閱

三、七大實戰範例

範例 1：最簡單的 HTTP GET

CURL *curl = curl_easy_init();
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
curl_easy_perform(curl);
curl_easy_cleanup(curl);

範例 2：HTTPS 忽略憑證驗證（測試用）

curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);

範例 3：客戶端憑證認證（雙向 TLS）

curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM");
curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM");
curl_easy_setopt(curl, CURLOPT_SSLKEY, "client.key");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "passphrase");
curl_easy_setopt(curl, CURLOPT_CAINFO, "ca.pem");
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);

範例 4：分離 HTTP Header 與 Body 存檔

curl_easy_setopt(curl, CURLOPT_HEADERDATA, header_fp);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, body_fp);

範例 5：HTTP PUT 上傳檔案

curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
curl_easy_setopt(curl, CURLOPT_PUT, 1L);
curl_easy_setopt(curl, CURLOPT_READDATA, fp);
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, filesize);

範例 6：multipart/form-data 檔案上傳（模擬瀏覽器表單）

struct curl_httppost *formpost = NULL, *lastptr = NULL;
curl_formadd(&formpost, &lastptr,
    CURLFORM_COPYNAME, "sendfile",
    CURLFORM_FILE, "localfile.txt",
    CURLFORM_END);
curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);

範例 7：除錯追蹤完整協定交互

curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &config);
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);

四、編譯與連結

gcc -o example example.c -lcurl
# 或使用 pkg-config
gcc -o example example.c $(pkg-config --cflags --libs libcurl)

五、常見坑與建議

• 多執行緒環境必須在主執行緒呼叫 curl_global_init，避免重複初始化競爭。
• 回呼函數 CURLOPT_WRITEFUNCTION 可能被多次呼叫，需正確處理 size * nmemb 總長度。
• 大檔案下載請啟用 CURLOPT_NOPROGRESS=0 並設定進度回呼，避免長時間無回應被視為凍結。
• 生產環境嚴禁關閉 SSL 驗證，請正確部署 CA 憑證。