---

curl POST 终极教程：详解命令行发送 HTTP 请求

前言：HTTP 请求的基石与 curl 的力量

在现代网络应用中，HTTP（Hypertext Transfer Protocol）请求是客户端与服务器之间通信的基石。它定义了客户端如何向服务器请求资源，以及服务器如何响应。HTTP 请求主要分为几种方法（Methods），其中最常见的便是 GET 和 POST。GET 请求通常用于获取数据，其参数附加在 URL 之后，而 POST 请求则主要用于向服务器提交数据，如表单填写、文件上传或创建新资源，其数据体（request body）独立于 URL。

curl 是一个功能强大、用途广泛的命令行工具，它允许用户通过各种协议（包括 HTTP、HTTPS、FTP、FTPS 等）传输数据。对于开发者、测试人员和系统管理员而言，curl 是调试 API、自动化任务和测试网络连接的瑞士军刀。虽然它也能轻松发送 GET 请求，但其在处理 POST 请求方面的灵活性和深度，才是真正彰显其价值的地方。

本教程将深入探讨 curl 在发送 HTTP POST 请求时的各种用法、参数和最佳实践。我们将从最基础的 POST 请求开始，逐步覆盖不同数据格式（表单数据、JSON、XML、文件上传），以及如何控制请求头、处理认证、管理 Cookie、应对 SSL/TLS 问题、处理代理等高级主题。目标是让你在阅读完本文后，能够熟练地使用 curl 应对任何 POST 请求场景。

第一章：curl 的安装与基础认知

在开始之前，确保你的系统上已经安装了 curl。

1.1 curl 的安装

• Linux (Debian/Ubuntu):
  bash
sudo apt update
sudo apt install curl
• Linux (CentOS/Fedora):
  bash
sudo yum install curl # 或 sudo dnf install curl
• macOS: curl 通常是预装的。如果没有，可以通过 Homebrew 安装：
  bash
brew install curl
• Windows:
  • curl 从 Windows 10 build 17063 开始也已内置。在 PowerShell 或 CMD 中直接输入 curl 即可。
  • 如果版本较旧，可以从 curl 官方网站 (https://curl.se/download.html) 下载预编译的二进制文件，并将其添加到系统 PATH 环境变量中。
  • 或者，在 WSL (Windows Subsystem for Linux) 中使用 Linux 版 curl。

1.2 检查 curl 版本

安装完成后，可以通过以下命令检查 curl 的版本信息：

bash
curl --version
这将显示 curl 的版本号、支持的协议和特性，确认其正常工作。

第二章：构建最简单的 POST 请求

发送一个 POST 请求，最核心的要素是指定请求方法为 POST，并提供目标 URL。

2.1 指定 POST 方法：-X POST

尽管 curl 在发送数据时通常会自动切换到 POST 方法，但明确指定 POST 方法是一个好习惯，可以避免歧义并增强可读性。

bash
curl -X POST <URL>

例如，我们可以使用一个公共的测试服务 httpbin.org 来发送一个空的 POST 请求：

bash
curl -X POST https://httpbin.org/post

预期输出：
httpbin.org/post 会返回一个 JSON 格式的响应，其中包含你请求的详细信息。对于一个空的 POST 请求，form、data、json 等字段通常会是空的。

json
{
"args": {},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Content-Length": "0",
"Host": "httpbin.org",
"User-Agent": "curl/7.64.1"
},
"json": null,
"origin": "your_ip_address",
"url": "https://httpbin.org/post"
}
注意 Content-Length: 0 和 data: "" 表示没有发送任何数据。

第三章：发送数据：POST 请求的核心

POST 请求的真正威力在于能够向服务器提交数据。curl 提供了多种方式来发送不同格式的数据。

3.1 发送 URL 编码的表单数据 (application/x-www-form-urlencoded)

这是最常见的 POST 数据格式，尤其是在传统的 HTML 表单提交中。数据以 key=value&key2=value2 的形式编码。

3.1.1 使用 -d 或 --data

curl 的 -d 或 --data 选项是发送 POST 数据的核心。当使用此选项时，curl 会自动将请求方法设置为 POST（如果之前没有明确指定），并将 Content-Type 头设置为 application/x-www-form-urlencoded。

基本语法：
bash
curl -X POST -d "key1=value1&key2=value2" <URL>

示例：提交用户名和密码
bash
curl -X POST -d "username=john.doe&password=securepassword123" https://httpbin.org/post

预期输出：
在 httpbin.org/post 的响应中，你会看到 form 字段包含了你提交的数据。
json
{
// ... 其他字段
"form": {
"password": "securepassword123",
"username": "john.doe"
},
// ...
}

发送多个 -d 参数：
如果你使用多个 -d 选项，curl 会将它们合并起来，用 & 连接。
bash
curl -X POST -d "username=jane.smith" -d "[email protected]" https://httpbin.org/post
这等同于 -d "username=jane.smith&[email protected]"。

处理特殊字符：
URL 编码会自动处理大多数特殊字符（如空格会被转换为 + 或 %20）。但如果你的数据本身包含 & 或 = 等 URL 分隔符，你需要使用引号来包裹整个数据字符串，或者进行手动编码。

3.1.2 从文件读取数据：@filename

当数据量较大或包含复杂内容时，将其存放在文件中然后让 curl 读取是一个好方法。

语法：
bash
curl -X POST -d "@path/to/data.txt" <URL>
文件 data.txt 中的内容将作为请求体发送。

示例：
1. 创建一个文件 user_data.txt：
name=Alice Wonderland&age=30&city=New York
2. 发送 POST 请求：
bash
curl -X POST -d "@user_data.txt" https://httpbin.org/post
预期输出：
form 字段将显示文件中的数据。

3.1.3 精确控制编码：--data-urlencode

-d 选项会默认对所有数据进行 URL 编码。但有时你可能需要更精细的控制，例如只对值进行编码，或者指定不同的编码方式。--data-urlencode 提供了这种能力。

语法：
* --data-urlencode "name=value"：对 name 和 value 都进行编码。
* --data-urlencode "name@filename"：读取文件内容作为 value，并对其进行编码。
* --data-urlencode "name=value"：对 value 进行编码，name 不编码。
* --data-urlencode "name=<file"：读取文件内容作为 value，并对其进行编码（旧版用法）。

示例：编码特殊字符
如果 value 包含空格、& 等，使用 --data-urlencode 可以确保它们被正确编码。

bash
curl -X POST --data-urlencode "message=Hello World & Goodbye!" https://httpbin.org/post
预期输出：
form 中 message 的值将是 Hello+World+&+Goodbye%21 或类似的编码形式。

3.2 发送 JSON 数据 (application/json)

JSON (JavaScript Object Notation) 是现代 Web API 中最流行的数据交换格式。发送 JSON 数据需要明确设置 Content-Type 请求头。

3.2.1 使用 -d 结合 -H "Content-Type: application/json"

这是发送 JSON 数据最常用的方式。Content-Type 头告诉服务器请求体是 JSON 格式。

语法：
bash
curl -X POST -H "Content-Type: application/json" -d '{"key": "value", "number": 123}' <URL>
注意： JSON 字符串必须用单引号 ' 包裹，以避免 shell 解析其中的双引号 "。

示例：提交一个 JSON 对象
bash
curl -X POST -H "Content-Type: application/json" -d '{"id": 101, "name": "John Doe", "active": true}' https://httpbin.org/post

预期输出：
响应中的 json 字段将包含你提交的 JSON 数据。
json
{
// ...
"json": {
"active": true,
"id": 101,
"name": "John Doe"
},
// ...
}

3.2.2 从文件读取 JSON 数据：@filename

对于复杂的 JSON 结构，将其保存在文件中是更清晰的做法。

语法：
bash
curl -X POST -H "Content-Type: application/json" -d "@path/to/data.json" <URL>

示例：
1. 创建文件 user.json：
json
{
"username": "api_user",
"email": "[email protected]",
"roles": ["admin", "editor"]
}
2. 发送 POST 请求：
bash
curl -X POST -H "Content-Type: application/json" -d "@user.json" https://httpbin.org/post
预期输出：
json 字段将显示文件中的 JSON 数据。

3.3 发送 XML 数据 (application/xml)

虽然不如 JSON 流行，但在一些企业级应用或遗留系统中，XML 仍然是数据交换格式。发送 XML 数据与 JSON 类似，只是 Content-Type 不同。

语法：
bash
curl -X POST -H "Content-Type: application/xml" -d '<root><item id="1">data</item></root>' <URL>

示例：提交一个 XML 文档
bash
curl -X POST -H "Content-Type: application/xml" -d '<product><name>Laptop</name><price>1200.00</price></product>' https://httpbin.org/post

3.3.1 从文件读取 XML 数据：@filename

同理，XML 数据也可以从文件读取。

语法：
bash
curl -X POST -H "Content-Type: application/xml" -d "@path/to/data.xml" <URL>

3.4 文件上传：Multipart Form Data (multipart/form-data)

当需要上传文件以及其他表单字段时，multipart/form-data 是标准的编码类型。curl 的 -F 或 --form 选项专门用于处理这种请求。

语法：
* 发送普通字段：-F "key=value"
* 上传文件：-F "file=@/path/to/local/file"
* 上传文件并指定文件名和类型：-F "file=@/path/to/local/file;filename=remote_name.ext;type=image/jpeg"

示例：上传一个文本文件并附加描述
1. 创建一个名为 upload_me.txt 的文件，内容随意。
bash
echo "This is a test file for upload." > upload_me.txt
2. 发送 POST 请求：
bash
curl -X POST -F "document=@upload_me.txt" -F "description=A document uploaded via curl" https://httpbin.org/post

预期输出：
响应中会有一个 files 字段包含上传的文件内容，form 字段包含其他表单数据。
json
{
// ...
"files": {
"document": "This is a test file for upload.\n"
},
"form": {
"description": "A document uploaded via curl"
},
// ...
}

示例：上传图片并指定 Content-Type
假设你有一个名为 my_image.jpg 的图片文件。
bash
curl -X POST -F "image=@my_image.jpg;type=image/jpeg" -F "caption=A beautiful sunset" https://httpbin.org/post
这里的 type=image/jpeg 告诉服务器这个文件是 JPEG 图片。

3.5 发送原始数据 (--data-raw 或 --data-binary)

有时你可能需要发送未经过 curl 任何处理的原始数据，例如，当数据本身已经是特定格式（如序列化的二进制数据）并且你不想让 curl 进行 URL 编码时。

3.5.1 --data-raw

--data-raw 选项会按原样发送数据，不会进行 URL 编码。它会自动设置 Content-Type: application/x-www-form-urlencoded，但数据本身不会被编码。如果需要不同的 Content-Type，你需要手动添加。

示例：发送原始 JSON 字符串 (不推荐用于 JSON，但展示其效果)
bash
curl -X POST --data-raw '{"key": "value"}' https://httpbin.org/post
尽管数据是 JSON 格式，curl 默认会将其视为 application/x-www-form-urlencoded。在 httpbin.org 的响应中，你会看到 data 字段包含原始字符串，但 json 字段为 null。

为了正确发送原始 JSON，你需要同时指定 Content-Type：
bash
curl -X POST -H "Content-Type: application/json" --data-raw '{"key": "value"}' https://httpbin.org/post
这与使用 -d 效果相同。通常，对于文本数据，-d 更常用，因为它会自动处理 URL 编码。

3.5.2 --data-binary

--data-binary 与 --data-raw 类似，但它在处理文件时特别有用，因为它不会对文件内容进行任何处理，包括回车换行符的转换。这对于传输二进制文件（如图片、压缩包）非常重要。

示例：传输二进制文件
1. 创建一个小型的二进制文件（例如，一个空的 zip 文件或任意图像文件）。
2. 发送：
bash
curl -X POST --data-binary "@my_binary_file.zip" -H "Content-Type: application/octet-stream" https://httpbin.org/post
这里 application/octet-stream 是通用的二进制流类型。

第四章：控制 POST 请求的方方面面

除了数据本身，curl 还提供了大量选项来精细控制 POST 请求的各个方面。

4.1 HTTP 请求头 (-H 或 --header)

HTTP 头是请求和响应中包含的元数据。它们提供了关于请求（如客户端类型、接受的语言）或响应（如内容类型、缓存指令）的额外信息。

语法：
bash
curl -H "Header-Name: Header-Value" <URL>
你可以使用多个 -H 选项来添加多个头。

常用示例：

• User-Agent: 模拟不同的浏览器或客户端。
  bash
curl -X POST -H "User-Agent: MyCustomApp/1.0" -d "data=test" https://httpbin.org/post
• Accept: 告诉服务器客户端可以接受的响应内容类型。
  bash
curl -X POST -H "Accept: application/json" -d "data=test" https://httpbin.org/post
• Authorization: 发送认证凭证，如 Bearer Token。
  bash
curl -X POST -H "Authorization: Bearer YOUR_AUTH_TOKEN" -d '{"message": "secret"}' https://your-api.com/secure_endpoint
• 自定义头： 发送应用程序特有的头。
  bash
curl -X POST -H "X-API-Key: YOUR_API_KEY" -d "data=value" https://your-api.com/data

4.2 认证 (-u 或 --user)

curl 支持多种认证方式。

4.2.1 HTTP Basic Authentication (基本认证)

基本认证通过 Authorization 头发送 Base64 编码的用户名和密码。

语法：
bash
curl -u "username:password" -X POST -d "data=test" <URL>
示例：
bash
curl -u "admin:secret" -X POST -d "status=active" https://httpbin.org/basic-auth/admin/secret

4.2.2 其他认证方式
对于 Bearer Token、OAuth 等认证，通常是作为自定义 Authorization 头发送的，如 4.1 节所示。

4.3 Cookie (-b 和 -c)

Cookie 是服务器发送到用户浏览器并保存在本地的数据，通常用于维持会话状态。

4.3.1 发送 Cookie (-b 或 --cookie)

当你需要发送之前从服务器获取的 Cookie 时。

语法：
* 直接提供 Cookie 字符串：-b "name=value; name2=value2"
* 从文件读取 Cookie：-b cookie_file.txt (文件内容格式通常是 Netscape Cookie File format)

示例：发送会话 Cookie
bash
curl -X POST -b "session_id=abcdef123456" -d "action=update" https://your-api.com/profile

4.3.2 保存 Cookie (-c 或 --cookie-jar)

将服务器响应中的 Cookie 保存到文件中，以便后续请求使用。

语法：
bash
curl -c cookie_jar.txt <URL>

组合使用示例：
1. 首先，获取并保存 Cookie：
bash
curl -c my_cookies.txt https://your-api.com/login_page
2. 然后，使用保存的 Cookie 发送 POST 请求：
bash
curl -X POST -b my_cookies.txt -d "username=user&password=pass" https://your-api.com/do_login
（注意：真实的登录可能需要 CSRF token 等，这里仅作示例。）

4.4 代理 (-x 或 --proxy)

通过代理服务器发送请求。

语法：
bash
curl -x "http://proxy.example.com:8080" -X POST -d "data=test" <URL>
支持 HTTP、HTTPS、SOCKS4、SOCKS5 代理。如果代理需要认证，可以使用 -U "user:pass" 选项。

4.5 SSL/TLS 证书 (-k, --cacert, --cert)

处理 HTTPS 连接的证书验证。

• 忽略 SSL/TLS 证书验证 (-k 或 --insecure)：
  在测试或开发环境中，服务器的 SSL 证书可能无效或自签名。使用 -k 可以绕过证书验证，但在生产环境中应避免使用，因为它会降低安全性。
  bash
curl -k -X POST -d "data=test" https://self-signed-cert.com/api
• 指定 CA 证书 (--cacert)：
  当服务器使用非标准或自定义的 CA 签名的证书时，你可以指定 CA 证书文件。
  bash
curl --cacert /path/to/ca.pem -X POST -d "data=test" https://your-internal-api.com
• 客户端证书认证 (--cert, --key)：
  一些 API 要求客户端也提供证书进行身份验证。
  bash
curl --cert /path/to/client.pem --key /path/to/client.key -X POST -d "data=test" https://secure-api.com

4.6 请求超时 (--max-time, --connect-timeout)

控制请求的最大允许时间和连接建立的最大时间。

• --max-time <seconds>: 整个请求过程的最大允许时间。
• --connect-timeout <seconds>: 建立连接阶段的最大允许时间。

示例：
bash
curl --max-time 10 --connect-timeout 5 -X POST -d "data=test" https://slow-api.com

4.7 重定向 (-L 或 --location)

默认情况下，curl 不会自动跟随 HTTP 3xx 重定向。使用 -L 选项可以使其跟随。

bash
curl -L -X POST -d "data=test" https://short-url.com/redirect_to_actual_post

注意： 当使用 -L 且原始请求是 POST 时，curl 会在重定向后将请求方法改为 GET，并丢弃 POST 数据。如果需要保持 POST 方法，应使用 --post301, --post302, --post303 (如果你的 curl 版本支持)。更通用的做法是在每次重定向时都显式指定 POST。例如，对于 301/302，许多服务期望客户端将它们转换为 GET。如果服务器明确期望重定向后仍为 POST，这需要服务器端的特定处理。

第五章：输出控制与调试

curl 不仅仅是一个发送请求的工具，它也是一个强大的调试利器。

5.1 显示详细信息 (-v 或 --verbose)

这是调试请求时最重要的选项。它会显示请求和响应的详细过程，包括发送的头、接收的头、SSL 握手信息等。

bash
curl -v -X POST -d "username=debug" https://httpbin.org/post
你会看到箭头 > 表示发送的请求头和数据，< 表示接收到的响应头和数据。

5.2 只显示响应头 (-i 或 --include)

在响应体之前包含 HTTP 响应头。
bash
curl -i -X POST -d "data=test" https://httpbin.org/post

5.3 静默模式 (-s 或 --silent)

抑制 curl 的进度条和错误信息。通常与 -o (输出到文件) 或 -w (写入自定义信息) 结合使用。

bash
curl -s -X POST -d "data=test" https://httpbin.org/post -o response.json
这会将响应体保存到 response.json 文件中，而不在终端显示进度信息。

5.4 将输出保存到文件 (-o 或 --output)

将服务器的响应体保存到指定的文件中。

bash
curl -X POST -d "data=test" https://httpbin.org/post -o api_response.json

5.5 自动命名文件 (-O 或 --remote-name)

如果 URL 指向一个文件，这个选项会根据 URL 中的文件名将响应保存到本地文件中。对于 POST 请求，通常不直接返回文件，但在某些特定场景下可能有用。

5.6 写入自定义信息 (-w 或 --write-out)

一个非常强大的选项，可以让你在请求完成后，按照自定义格式输出请求的统计信息，如状态码、总时间、下载速度等。

语法：
bash
curl -w "HTTP Status: %{http_code}\nTotal Time: %{time_total}s\n" -X POST -d "data=test" https://httpbin.org/post
%{...} 是 curl 提供的变量。这对于性能测试和自动化脚本非常有用。

第六章：高级话题与最佳实践

6.1 结合 jq 处理 JSON 响应

当 curl 返回 JSON 响应时，jq 是一个命令行 JSON 处理器，可以帮助你美化、过滤和提取 JSON 数据。

示例：格式化 JSON 响应并提取特定字段
bash
curl -s -X POST -H "Content-Type: application/json" -d '{"name": "Alice", "age": 30}' https://httpbin.org/post | jq '.'
输出将是格式化后的 JSON。

bash
curl -s -X POST -H "Content-Type: application/json" -d '{"name": "Alice", "age": 30}' https://httpbin.org/post | jq '.json.name'
这将只输出 "Alice"。

6.2 Shell 脚本中的 curl

curl 经常用于 Shell 脚本中进行自动化操作。

示例：上传文件并根据响应做判断
“`bash

!/bin/bash

FILE_TO_UPLOAD=”report.txt”
UPLOAD_URL=”https://your-api.com/upload”
API_KEY=”YOUR_SECRET_API_KEY”

if [ ! -f “$FILE_TO_UPLOAD” ]; then
echo “Error: File $FILE_TO_UPLOAD not found!”
exit 1
fi

RESPONSE=$(curl -s -X POST -H “X-API-Key: $API_KEY” -F “document=@$FILE_TO_UPLOAD” “$UPLOAD_URL”)
HTTP_CODE=$(echo “$RESPONSE” | jq -r ‘.code // empty’) # 假设响应中有code字段
MESSAGE=$(echo “$RESPONSE” | jq -r ‘.message // empty’)

if [ “$HTTP_CODE” == “200” ]; then
echo “File uploaded successfully: $MESSAGE”
else
echo “File upload failed: HTTP Code $HTTP_CODE, Message: $MESSAGE”
echo “Full Response: $RESPONSE”
fi
“`

6.3 避免在命令行中暴露敏感信息

直接在命令行中输入密码或 API 密钥存在安全风险，因为这些信息可能会被存储在 Shell 历史记录中。

• 使用环境变量：
  bash
export API_KEY="your_secret_key"
curl -H "X-API-Key: $API_KEY" ...
  （注意：环境变量也可能被其他进程看到，但比历史记录安全一些）
• 交互式输入密码：
  对于 Basic Auth，可以省略密码部分，curl 会提示你输入：
  bash
curl -u "username" -X POST ...
• 从文件读取密码或 token：
  对于某些需要密码的文件，curl 可以从文件读取。对于自定义头，可以将敏感信息存入文件，然后使用 $(cat file) 动态读取。
  bash
echo "YOUR_AUTH_TOKEN" > token.txt
curl -H "Authorization: Bearer $(cat token.txt)" ...
rm token.txt # 用完即删

6.4 常见问题与排错

• Content-Type 不匹配： 服务器期望 JSON 但你发送了表单数据，反之亦然。检查响应是否是服务器报错，并使用 -v 观察请求头。
• JSON 格式错误： JSON 字符串中的引号未转义、逗号缺失或多余等。使用 jq 或在线 JSON 校验工具检查。
• 文件路径错误： -d "@filename" 或 -F "file=@filename" 中的文件路径不正确。
• URL 错误： 协议错误、主机名错误、路径错误。
• 网络问题： 防火墙、代理设置、目标服务器不可达。
• 权限问题： API 密钥无效、认证失败。

当遇到问题时，始终从以下几步开始：
1. 使用 -v 选项： 观察请求和响应的完整过程。
2. 检查 Content-Type： 确保它与你发送的数据格式匹配。
3. 检查响应状态码： 200 OK (成功), 400 Bad Request (客户端请求错误), 401 Unauthorized (未认证), 403 Forbidden (无权限), 404 Not Found (资源不存在), 500 Internal Server Error (服务器内部错误) 等。
4. 仔细阅读服务器返回的错误信息： 很多 API 会在响应体中给出详细的错误描述。

总结

curl 是一个极其强大且多功能的命令行工具，对于任何需要与 Web 服务交互的人来说都是必备技能。通过本文的详细讲解，你应该已经掌握了使用 curl 发送各种类型的 HTTP POST 请求的技巧：

• 从最基本的表单数据到复杂的 JSON、XML 和文件上传。
• 如何精确控制 HTTP 请求头、进行身份验证、管理 Cookie。
• 如何处理代理、SSL/TLS 证书问题。
• 以及如何利用 curl 的调试功能进行故障排查。

熟练运用这些知识，将使你在 API 开发、测试、自动化运维和日常网络调试工作中如虎添翼。记住，实践是最好的老师，多加尝试和探索，你将发现 curl 的更多奥秘和无限可能。祝你在 curl 的世界中探索愉快！

---