告别cURL头痛：几秒内构建复杂命令

如果您做开发超过几个月，就一定用过cURL。您可能也不止一次Google过"curl post request json"。这没什么丢人的——cURL有很多标志，语法密集到连经验丰富的开发者也不会全部记住。

大多数开发者没有意识到的是，您只需要深入理解大约十几个标志，就能覆盖日常API测试需求的90%。其余的可以在需要时查阅，或者使用构建器来组装命令，无需记忆语法。

本指南专注于cURL中真正重要的部分，并附上您今天就能运行的实际示例。

为什么要用cURL？

这是个合理的问题。您有Postman、Insomnia、VS Code的REST Client扩展、浏览器开发工具——为什么还要用cURL？

几个原因：

随处可用。 cURL预装在macOS和大多数Linux系统上。在全新服务器上、Docker容器中、同事的机器上——cURL都可用。Postman则不一定。

可脚本化。 您可以将cURL命令放入bash脚本、CI管道、定时任务、Makefile中。它成为您基础设施的一部分。GUI工具无法做到这一点。

易于分享。 将cURL命令粘贴到Slack消息或GitHub Issue中，任何人都可以立即运行。不需要"这是在Postman中重现的步骤"之类的说明。

通用语言。 大多数API文档都展示cURL示例。当同事说"这是失败的请求"时，他们通常会发送一个cURL命令。能读懂cURL是值得培养的技能。

也就是说，cURL并不总是正确的工具。复杂的多步骤工作流、可视化响应检查，或涉及大量表单数据的操作，通常在Postman中更容易管理。请根据需求选择合适的工具。

您实际会用到的标志

-X — HTTP方法

默认情况下，cURL发送GET请求。使用-X来更改方法：

curl -X POST https://api.example.com/users
curl -X PUT https://api.example.com/users/123
curl -X DELETE https://api.example.com/users/123
curl -X PATCH https://api.example.com/users/123

一个常见简写：当您使用-d发送请求体时，可以省略-X POST，因为cURL会推断出POST方法。但明确写出来更清晰，尤其是在与他人分享命令时。

-H — 添加请求头

您发出的几乎每个API请求都需要至少一个请求头。POST/PUT请求需要Content-Type，认证端点需要Authorization：

# 设置内容类型
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json"

# 添加认证令牌
curl https://api.example.com/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# 多个请求头
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Request-ID: abc123"

您可以在同一命令中多次使用-H，每个标志对应一个请求头。

-d — 请求体

在请求体中发送数据。用于POST、PUT和PATCH请求：

# JSON请求体
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# 表单数据（URL编码）
curl -X POST https://api.example.com/login \
  -d "username=alice&password=secret"

关于缺少Content-Type请求头的说明：如果您发送带JSON的-d但忘记了-H "Content-Type: application/json"，服务器可能会拒绝请求或错误解析请求体。这是最常见的cURL错误之一。当您知道发送的是什么时，请始终设置Content-Type。

-L — 跟随重定向

默认情况下，如果服务器返回301或302重定向，cURL会停止并显示重定向响应。通常您希望跟随它：

curl -L https://example.com/old-url

在处理将HTTP重定向到HTTPS的API，或资源已移动的情况时，这种情况经常出现。没有-L，您只会看到301 Moved Permanently，然后不知道为什么请求没有返回数据。

-i — 包含响应头

默认情况下，cURL只显示响应体。-i还会包含响应头：

curl -i https://api.example.com/users/1

输出看起来像这样：

HTTP/2 200
content-type: application/json
x-rate-limit-remaining: 99
...

{"id": 1, "name": "Alice"}

当您需要检查状态码、Content-Type、缓存头或速率限制信息时，这非常有用。在只需要请求头而不需要完整连接调试输出的情况下，-i是详细模式的轻量级替代方案。

-v — 详细模式

这是调试标志。-v显示所有内容：cURL发送的完整请求头、TLS握手以及完整的响应头：

curl -v https://api.example.com/users

示例输出（简略版）：

* Trying 93.184.216.34:443...
* Connected to api.example.com (93.184.216.34) port 443
* SSL connection using TLSv1.3
> GET /users HTTP/2
> Host: api.example.com
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/2 200
< content-type: application/json
<
{"users": [...]}

以>开头的行是cURL发送的内容。以<开头的行是服务器发回的内容。以*开头的行是cURL自身的状态消息。在调试认证问题、意外的请求头或TLS问题时，这非常有价值。

-u — 基本认证

对于使用HTTP基本认证的API，您可以手动构建Authorization请求头，但-u会自动完成这个操作：

curl -u username:password https://api.example.com/protected

cURL将凭据编码为Base64并发送正确的Authorization: Basic ...请求头。需要注意的是：如果您在终端中粘贴此命令，您的密码会出现在Shell历史记录中。要么之后清除历史记录，要么使用环境变量：

curl -u "alice:$API_PASSWORD" https://api.example.com/protected

-k — 跳过SSL验证

这个标志需要谨慎使用。-k（或--insecure）告诉cURL忽略SSL证书错误：

curl -k https://localhost:8443/api/health

在使用自签名证书的本地开发环境中，这是合理的。但对于生产请求则不然。如果您对真实的外部服务使用-k，您就在绕过出于充分理由而存在的安全措施。仅在开发环境中使用它。

-o和-O — 将响应保存到文件

将响应保存到文件而不是打印到终端：

# 保存到指定文件名
curl -o output.json https://api.example.com/data

# 使用远程文件名保存
curl -O https://example.com/files/report.pdf

-o让您选择文件名，-O使用URL最后一段路径作为文件名。

-s — 静默模式

抑制进度条和错误消息。在脚本中只想要响应体时很有用：

curl -s https://api.example.com/status | jq .

管道传输给jq是美化JSON响应的常见模式。-s保持输出干净，这样jq只接收到JSON。

常见错误

POST请求忘记Content-Type

这个错误每次都会让开发者吃苦头。您发送的是JSON，服务器返回400 Bad Request或415 Unsupported Media Type，您花20分钟调试才意识到修复方法是添加一个请求头：

# 缺少请求头——服务器可能拒绝此请求
curl -X POST https://api.example.com/users \
  -d '{"name": "Alice"}'

# 正确写法
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Windows上的引号问题

Windows命令提示符中的cURL处理引号的方式与bash不同。单引号在CMD中不起作用。您需要使用双引号并转义内部引号：

# Windows CMD——使用双引号，转义内部引号
curl -X POST https://api.example.com/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\": \"Alice\"}"

在PowerShell中，单引号有效，但转义规则仍然不同。这是Windows开发者使用为Unix系统编写的文档中的cURL命令时最大的困惑来源之一。如果您在Windows上使用文档中的cURL命令不起作用，引号通常是罪魁祸首。

发送文件时忘记使用@

当您想将文件内容作为请求体发送时，使用@文件名：

# 将data.json的内容作为请求体发送
curl -X POST https://api.example.com/import \
  -H "Content-Type: application/json" \
  -d @data.json

没有@，cURL会将字符串视为字面请求体值，而不是文件名。您将发送字面文本data.json而不是文件内容。

对GET请求使用-d

-d发送请求体。GET请求没有请求体（服务器通常会忽略它）。如果您想通过GET请求发送查询参数，请将它们放在URL中：

# GET请求带参数的正确写法
curl "https://api.example.com/users?page=1&limit=20"

注意URL周围的引号。没有引号，URL中的&可能被Shell解释为后台操作符。

综合运用：实际示例

创建用户：

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Bob", "email": "bob@example.com", "role": "editor"}'

上传文件：

curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "description=Q4 Report"

（注意：多部分表单数据使用-F，而不是-d）

使用自定义负载测试Webhook：

curl -X POST https://your-app.com/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=abc123" \
  -d @sample-push-event.json

带进度显示的下载：

curl -L -o large-file.zip https://example.com/downloads/archive.zip

使用构建器代替记忆

对于简单GET请求之外的任何操作，从记忆中组合正确的标志组合会令人疲惫。ToolPal cURL命令构建器让您通过表单填写方法、URL、请求头和请求体，并为您生成cURL命令——然后您可以直接复制到终端或根据需要调整。

这对于以下情况特别有用：

• 构建包含您之前未写过的认证请求头的命令
• 正确处理多部分表单上传的语法
• 为习惯了bash的您生成Windows兼容命令
• 与可能不了解标志语法的团队成员分享命令

生成的命令是标准cURL——没有厂商锁定，没有专有内容。您将构建器作为生产力工具，然后将生成的命令用于任何需要的地方。

cURL与其他工具的比较

cURL与Postman： Postman在迭代式API探索、管理请求集合和团队协作方面更胜一筹。cURL在脚本编写、快速一次性请求和分享性方面更有优势。它们不是竞争对手——大多数开发者两者都用。

cURL与HTTPie： HTTPie是一个更新的命令行HTTP客户端，界面更友好，输出更美观。如果您愿意安装它，值得一试。cURL的优势在于无需安装即可在任何地方使用。

cURL与浏览器开发工具： 对于检查浏览器实际发送的内容（Cookie、Session令牌、复杂请求头），开发工具无与伦比。您甚至可以在Network标签页中右键点击请求并将其复制为cURL命令——这是从命令行重现浏览器请求的有用方法。

---

cURL回报您投入学习它的时间。即使您永远不会记住所有标志，理解核心标志的工作原理——-X、-H、-d、-L、-v——也能给您一个随处可用、易于脚本化、表达清晰的工具。这比记住任何数量的语法模式都更有价值。

有疑问时，使用构建器。需要理解出了什么问题时，使用-v。