关键要点
- cURL是一种快速、可编写脚本的命令行工具，无需依赖浏览器或图形界面即可发送请求。
- 它支持所有主流 HTTP 方法、身份验证类型、请求头以及文件上传和会话处理。
- 借助正确的语法和调试参数，cURL 可成为测试、自动化和排查 API 工作流程问题的可靠工具。
cURL（读作“curl”）是一种广受欢迎的开源命令行工具，用于在服务器与客户端之间传输数据。它支持多种协议（HTTP、HTTPS、FTP 等），常用于直接从终端发送网络请求。
在实际工作中，开发者常使用 cURL 向网络服务发送 HTTP 请求，例如测试某个 Web REST API 端点，或在无需浏览器的情况下与远程服务器交互。
本指南将介绍如何使用 cURL 发送 API 请求（GET、POST、PUT/PATCH、DELETE），并提供添加请求头、身份验证（Basic 和 Bearer 令牌）、发送 JSON 请求体的实际示例，以及一些排查问题的技巧。
cURL 用于 API 请求的基本语法
cURL 命令的基本语法如下：
curl [options] [URL]
使用 cURL 调用 API 时，通常需要加入一些选项（即参数）来自定义请求。以下是 API 调用中最常用的几个选项：
- -X（请求方法）：指定 HTTP 方法（如 GET、POST、PUT、DELETE）。如果不指定，cURL 对 HTTP URL 默认使用 GET 方法。例如，-X POST 会将请求方法设为 POST。
- -H（请求头）：为请求添加HTTP 请求头，可用于设置 Content-Type、Accept 或身份验证令牌等自定义请求头。
- -d（数据）：在请求体中发送数据，常与 POST 或 PUT 请求搭配使用，用于发送 JSON 或表单数据。
- -u（用户身份验证）：添加 Basic HTTP 基本身份验证凭据，语法为 -u username:password。
- -i 或 -v（查看响应）：使用 -i 可在 cURL 输出中包含 HTTP 响应头，便于查看状态码和请求头；使用 -v 开启详细模式，打印请求和响应的详细信息。
示例：一条结合多个选项的 cURL 命令可能如下所示：
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}' \
https://api.example.com/users
在这条命令中，-X POST 将方法指定为 POST，Content-Type 请求头设置为JSON，-d 参数发送包含 name 和 email 的 JSON 请求体。执行后，cURL 会将这些数据 POST 到该 API 的 /users 端点。
API 请求中常用的 cURL 命令
下面来看如何通过cURL 搭配代理使用指南执行最常见的 HTTP 请求，包括 GET、添加请求头、POST、PUT/PATCH 和 DELETE 的示例。
GET 请求示例
由于 GET 是默认方法，简单的 GET 请求无需额外参数，只需提供 URL 即可。例如，从示例 API 中获取 ID 为 1 的用户：
curl https://api.example.com/users/1
该命令会向指定 URL 发送 HTTP GET 请求，并在终端打印响应内容（例如该用户的 JSON 表示）。
带请求头的 GET 请求
有时需要在 GET 请求中加入请求头，例如指定响应格式或提供 API 密钥。可通过重复使用 -H 参数在 cURL 中添加一个或多个自定义请求头，例如：
curl -H "Accept: application/json" \
-H "X-API-Key: 12345" \
https://api.example.com/data
这里添加了两个请求头：Accept: application/json（用于请求 JSON 格式的响应）和一个用于身份验证的虚构 X-API-Key。服务器的响应（请求头和响应体）将被打印出来。
带 JSON 请求体的 POST 请求
通过 API 创建或添加数据通常使用 POST 方法。在 cURL 中，需指定 -X POST（如果使用 -d 未自动默认为该方法），并通过 -d 携带 JSON 数据。例如：
curl -X POST \
-H "Content-Type: application/json" \
-d '{"title": "New Item", "value": 42}' \
https://api.example.com/items
在此示例中，我们将 Content-Type 设置为 JSON，并在请求体中包含一个 JSON 对象。-d 参数负责发送数据；如果未指定内容类型，cURL 还会自动添加 Content-Length 请求头，并默认使用 Content-Type: application/x-www-form-urlencoded。
PUT/PATCH 请求示例
更新 API 中的数据通常使用 PUT 或 PATCH 方法，用法与 POST 类似：指定方法并携带数据。完整更新常用 PUT，部分更新则用 PATCH。例如，更新某用户的邮箱：
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"email": "new.email@example.com"}' \
https://api.example.com/users/123
该命令发送一个包含新邮箱的 JSON 请求体，用于更新 ID 为 123 的用户。此处使用 -X PUT 表示请求方法为 PUT。
DELETE 请求示例
要通过 cURL 删除某个资源，可在资源 URL 上使用 -X DELETE 参数，例如：
curl -X DELETE https://api.example.com/users/123
该命令会发送 HTTP DELETE 请求，删除 ID 为 123 的用户。除非 API 要求提供身份验证令牌或特定内容类型，否则通常无需请求体或额外的请求头。
在 cURL 中使用身份验证
许多 API 受到保护，需要进行身份验证，cURL 提供了简便的选项来处理常见的身份验证方案。
Basic 身份验证示例
Basic 身份验证将用户名和密码编码后放入 Authorization 请求头，在 cURL 中可通过 -u username:password 来处理。
例如，若某 API 端点要求 Basic 身份验证：
curl -u admin:secret https://api.example.com/protected/resource
cURL 会将 admin:secret 转换为 Authorization: Basic ... 请求头（凭据经过 Base64 编码）并加入请求中，省去了手动编码和添加请求头的步骤。
Bearer 令牌示例
另一种常见方案是Bearer 令牌身份验证（被 OAuth 2.0 等采用），需在请求头中提供访问令牌。在 cURL 中，需手动使用 -H "Authorization: Bearer <token>" 添加该请求头。
例如：
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
https://api.example.com/data
该命令将 Bearer 访问令牌附加到请求中以完成授权。实际使用时，需将 YOUR_TOKEN_HERE 替换为 API 提供的令牌字符串（通常是较长的 JWT 或随机字符串）。Authorization: Bearer ... 请求头用于告知服务器该请求携带了用于身份验证的令牌，请注意该请求头的名称和格式必须与 API 要求完全一致。
cURL 的高级 API 用法
除了基本的 GET/POST 调用外，cURL 还提供许多选项来处理更复杂的 API 交互，以下是几个高级使用场景：
发送多个请求头
前面提到，可以通过重复使用 -H 参数添加多个请求头。当需要在一条请求中发送多个请求头（例如多个令牌或自定义字段）时，这一方法十分有用，例如：
curl -H "Authorization: Bearer TOKEN123" \
-H "User-Agent: MyApp/1.0" \
-H "Accept-Language: en-US" \
https://api.example.com/endpoint
此处同时发送了三个请求头（Authorization、User-Agent 和 Accept-Language），只需为每个请求头键值对分别使用 -H 即可。
上传文件
可通过 cURL 的表单选项向 API 上传文件（例如图片或文档），最简单的方式是使用 -F（表单）选项，以 multipart/form-data 的形式模拟文件上传。
例如，若某 API 要求将文件放在名为“file”的字段下：
curl -X POST \
-H "Content-Type: multipart/form-data" \
-F "file=@/path/to/localfile.png" \
https://api.example.com/upload
此处，-F "file=@..." 告知 cURL 将本地文件（localfile.png）作为名为“file”的表单字段附加到请求中，cURL 会自动将其格式化为 multipart 表单请求（带有正确的边界符）并加入必要的请求头。
处理 Cookie 和会话
如果所交互的 API 使用 Cookie 进行会话管理（现代 API 中较少见，但在登录流程或 CSRF 令牌场景中仍会用到），cURL 同样可以处理 Cookie。可使用 -c 选项（Cookie 文件）保存 Cookie，使用 -b 选项（Cookie 文件或字符串）发送 Cookie。
例如：
# First, login and save cookies
curl -c cookies.txt -X POST -d "user=john&pass=doe" https://api.example.com/login
# Later, use saved cookies in another request
curl -b cookies.txt https://api.example.com/profile
在第一条命令中，-c cookies.txt 让 cURL 将服务器响应中设置的 Cookie 写入名为 cookies.txt 的文件；在第二条命令中，-b cookies.txt 加载这些 Cookie 并随请求一同发送，从而保持会话（如同同一客户端发出两次请求）。
自动跟随重定向（-L）
cURL 默认不会跟随 HTTP 重定向：如果 API 返回 3xx 重定向响应，cURL 只会显示该重定向响应本身。许多 API 不会重定向，但部分端点（或所请求的网页）可能会返回“Location”请求头（例如从 http:// 重定向到 https://）。
要让 cURL 自动跟随重定向，可使用 -L（或 --location）选项：
curl -L http://api.example.com/data
如果 http://api.example.com/data 返回 301/302 重定向到 https://api.example.com/data，-L 参数会让 cURL 自动在新 URL 上重试该请求。
用 cURL 自动化批量 API 请求更顺畅
获取数据中心代理为何选择 cURL 而非 Postman、Insomnia 等图形化工具？
既然有Postman或Insomnia等图形化工具可用于测试 API，您可能会好奇为何还要使用 cURL 这样的命令行工具。虽然这些工具界面友好，且更适合复杂测试和团队协作，但 cURL 也有自身的优势：
- 速度快、可编写脚本
cURL 轻量，可直接在终端运行，启动和使用都非常迅速。无需加载任何复杂界面，几秒钟内即可发出一条请求，这也意味着 cURL 很容易集成到脚本和自动化流程中。
例如，可以将 cURL 命令写入 Shell 脚本、CI/CD 流水线，或嵌入各类编程语言中，从而轻松实现自动化 API 调用或健康检查。
- 适合快速测试
如果只是想测试某个端点或复现某个请求，输入（或复制粘贴）一条 cURL 命令往往比使用图形化工具更快。在通过 SSH 登录服务器或仅有终端环境可用的场景下，cURL 是直接发送 API 请求不可或缺的工具。
在命令行工具之间难以抉择？我们的cURL 与 Wget对比文章将帮您分析哪一种更适合您的工作流程。
cURL 调用 API 的常见错误
使用 cURL 与 API 交互时，可能会遇到HTTP 错误，以下是几种常见错误及其处理方法，以及一些调试技巧：
- 401 未授权
401 错误表示请求缺少有效的身份验证凭据，换言之，服务器未接受您提供的凭据。这种情况通常发生在忘记携带令牌或 API 密钥，或令牌错误、已过期时。
- 400 错误请求
该状态码表示服务器无法理解您的请求，换句话说，问题出在客户端（也就是您）这边。如果您的 API 请求中存在错误，例如 URL 或请求头语法有误、JSON 请求体格式不正确，通常就会返回 400 错误。
如果遇到上述错误，cURL 的调试选项会非常有用。执行 cURL 时加上 -v（verbose）参数，可以在终端中打印完整的请求与响应详情（包括请求头、状态码，甚至 SSL 握手信息）。
如果需要更深入的信息，cURL 还提供了 --trace 选项。使用 --trace file.txt 可以将请求与响应的完整记录（包括二进制数据）写入指定文件，相当于对整个 HTTP 事务进行抓包记录，适合高级调试场景。
您也可以使用 --trace-ascii，在终端中获取便于阅读的追踪信息。
结语
掌握了上述调试技巧与分步示例后，您已经具备使用 cURL 与任意 REST API 交互的能力。如果您想分享经验、了解如何借助住宅代理传输数据，或与其他开发者交流心得，欢迎访问我们的Discord 社区，祝您使用 cURL 顺利！
