curl开发者快速入门

curl 开发者快速入门

精简版快速入门，只保留核心概念与上手步骤。构建与安装、基本用法示例、命令行选项、libcurl 架构与 API、简易/多接口、HTTP/TLS/协议支持、连接池与传输层、各协议实现（FTP/SFTP、SMTP/POP3、WebSocket）、认证与代理、URL API、平台相关等完整内容 详见 curl完整文档.md。

1. 一句话了解 curl

curl 是广泛使用的命令行工具 + 库 ：通过 URL 传输数据，支持 HTTP/HTTPS、FTP、SFTP、SMTP、MQTT、WebSocket 等众多协议。命令行 适合脚本与日常调试；libcurl 提供 C API，可集成到应用中，支持同步（easy 接口）与并发（multi 接口）。

为什么用？

协议全、跨平台、久经生产验证
命令行即装即用；libcurl API 稳定、文档与示例丰富
Easy 接口简单阻塞，Multi 接口可做高并发非阻塞

2. 双组件：命令行与 libcurl

组件	用途	典型场景
curl 命令行	URL 语法获取/发送数据	脚本、调试、CI、一次性请求
libcurl	可移植的客户端 URL 传输库	应用内 HTTP/FTP/自定义协议

libcurl 提供两种接口：

Easy 接口 ：curl_easy_init → curl_easy_setopt → curl_easy_perform → curl_easy_cleanup，阻塞式单传输。
Multi 接口 ：curl_multi_*，多句柄并发、非阻塞、可接入事件循环。

3. 5 分钟上手

安装

bash 复制代码

# macOS
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Windows (Chocolatey)
choco install curl

第一个命令

bash 复制代码

curl https://www.example.com/
curl -o page.html https://www.example.com/    # 保存到文件
curl -O https://example.com/file.zip           # 用远程文件名保存

常用选项：-o 保存到文件、-O 用远程文件名、-v 详细输出、-I 仅头、-L 跟随重定向、-u user:pass 认证。

4. 第一个 libcurl 程序

c 复制代码

#include <stdio.h>
#include <curl/curl.h>

int main(void) {
    CURL *curl;
    CURLcode res = curl_global_init(CURL_GLOBAL_ALL);
    if (res) return (int)res;

    curl = curl_easy_init();
    if (curl) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
        curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
        res = curl_easy_perform(curl);
        if (res != CURLE_OK)
            fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return (int)res;
}

编译（示例）：

bash 复制代码

# 使用 curl-config（若已安装开发包）
gcc -o myapp myapp.c $(curl-config --cflags --libs)

要点：程序启动时一次 curl_global_init，退出前一次 curl_global_cleanup；每次传输前 curl_easy_init，结束后 curl_easy_cleanup。

5. 常用选项与模式

需求	选项或做法
POST 数据	`CURLOPT_POSTFIELDS`、`CURLOPT_POSTFIELDSIZE`
响应写入内存	`CURLOPT_WRITEFUNCTION` + `CURLOPT_WRITEDATA`（回调中 realloc 追加）
响应写入文件	`CURLOPT_WRITEFUNCTION` 中 `fwrite`，`CURLOPT_WRITEDATA` 传 `FILE*`
HTTPS	使用 `https://` URL；生产环境勿关 `CURLOPT_SSL_VERIFYPEER`
错误处理	检查 `curl_easy_perform()` 返回的 `CURLcode`，用 `curl_easy_strerror(res)`
调试	`curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L)` 或命令行 `curl -v`

6. 下一步

完整文档 ：curl完整文档.md（从概述、快速开始到架构、easy/multi 深度解析、HTTP/TLS/协议实现、连接池与传输层、认证/代理/URL/平台等全章节）
官方：curl.se、everything.curl.dev、libcurl API
示例：仓库 docs/examples/、tests/

7. 常见问题

现象	可能原因	处理
链接/编译错误	未链接 libcurl 或头文件路径不对	使用 `curl-config --cflags --libs` 或正确指定 -I/-L
HTTPS 失败	证书验证或 CA 路径	检查 `CURLOPT_CAINFO`/`CURLOPT_CAPATH`；勿在生产环境关闭验证
无响应或卡住	未设超时、服务器无响应	设置 `CURLOPT_TIMEOUT`、`CURLOPT_CONNECTTIMEOUT`
需要并发	单线程多请求	使用 multi 接口：`curl_multi_*` + `curl_multi_wait`/`curl_multi_perform`

提示：生产代码中务必保留 SSL 证书验证；先用 CURLOPT_VERBOSE 或 curl -v 确认请求与响应行为。

curl开发者快速入门

curl 开发者快速入门

目录

1. 一句话了解 curl

2. 双组件：命令行与 libcurl

3. 5 分钟上手

安装

第一个命令

4. 第一个 libcurl 程序

5. 常用选项与模式

6. 下一步

7. 常见问题