cURL GET, POST, PUT, DELETE 完整指南 (2026)

cURL GET, POST, PUT, DELETE：2026 完整指南

cURL 是用于发送 HTTP 请求的通用命令行工具。它预装在 macOS 和大多数 Linux 发行版中，在 Windows 上也易于获取。无论你是在测试 API、调试 Webhook，还是在脚本中实现请求自动化，cURL 都是开发者的首选工具。

本指南涵盖了实际操作中会用到的所有 HTTP 方法：GET, POST, PUT, PATCH 和 DELETE，并提供了实际案例、常用参数（flags）以及可以直接复制到终端使用的模式。

快速参考表

方法	cURL 参数	用途	携带 Body
GET	默认（无需参数）	获取数据	否
POST	-X POST 或 --data	创建数据	是
PUT	-X PUT	替换数据	是
PATCH	-X PATCH	部分更新数据	是
DELETE	-X DELETE	移除数据	极少
HEAD	-I 或 -X HEAD	仅获取请求头	否
OPTIONS	-X OPTIONS	检查允许的方法	否

核心 cURL 参数

在深入案例之前，以下是你经常会用到的参数：

# 常用参数
-X METHOD          # 指定 HTTP 方法 (POST, PUT, DELETE 等)
-H "Header: Value" # 添加请求头
-d "data"          # 发送请求体数据
-i                 # 在输出中包含响应头
-v                 # 详细模式 (显示完整的请求/响应过程)
-s                 # 静默模式 (隐藏进度条)
-o filename        # 将输出保存到文件
-L                 # 跟随重定向
-k                 # 允许不安全的 SSL 连接
-u user:pass       # 基础认证 (Basic authentication)
-b "cookies"       # 发送 cookies
-c cookie-file     # 将 cookies 保存到文件
--max-time 30      # 30秒后超时

GET 请求

GET 是默认方法。你不需要使用 -X GET。

基础 GET：

curl https://jsonplaceholder.typicode.com/posts/1

带响应头的 GET：

curl -i https://jsonplaceholder.typicode.com/posts/1

带自定义请求头的 GET：

curl -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.example.com/users

带查询参数的 GET：

# 方案 1：包含在 URL 中
curl "https://api.example.com/search?q=hello&page=1&limit=10"

# 方案 2：配合 -G 参数使用 --data-urlencode
curl -G \
  --data-urlencode "q=hello world" \
  --data-urlencode "page=1" \
  https://api.example.com/search

获取并保存响应到文件：

curl -o response.json https://api.example.com/data

显示详细输出的 GET（非常适合调试）：

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

# 输出显示：
# > GET /health HTTP/2
# > Host: api.example.com
# > User-Agent: curl/8.x
# >
# < HTTP/2 200
# < content-type: application/json
# < ...

POST 请求

POST 用于创建新资源或提交数据。

使用 JSON 体进行 POST：

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

使用表单数据进行 POST：

curl -X POST https://api.example.com/login \
  -d "username=alice&password=secret123"

注意：当你使用 -d 时，cURL 会自动设置 Content-Type: application/x-www-form-urlencoded，除非你手动覆盖它。

使用来自文件的数据进行 POST：

# 从文件读取 JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

# 从标准输入 (stdin) 读取
echo '{"name": "Bob"}' | curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @-

上传文件的 POST (multipart form)：

curl -X POST https://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=Profile photo" \
  -F "userId=123"

上传多个文件的 POST：

curl -X POST https://api.example.com/upload \
  -F "files=@image1.jpg" \
  -F "files=@image2.png" \
  -F "files=@document.pdf"

PUT 请求

PUT 用于替换整个资源。请求体应包含更新后的完整资源。

使用 PUT 更新资源：

curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Updated",
    "email": "alice.new@example.com",
    "role": "senior-developer"
  }'

带身份验证的 PUT：

curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "name": "Alice Updated",
    "email": "alice.new@example.com",
    "role": "senior-developer"
  }'

PATCH 请求

PATCH 用于更新资源的特定字段，而不是替换整个资源。

使用 PATCH 更新特定字段：

curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{
    "role": "tech-lead"
  }'

PUT 与 PATCH 对比：

# PUT: 必须发送完整的资源
curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "role": "tech-lead",
    "department": "engineering"
  }'

# PATCH: 只需发送你想要更改的内容
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"role": "tech-lead"}'

DELETE 请求

DELETE 用于移除资源。大多数 DELETE 请求不需要请求体。

简单 DELETE：

curl -X DELETE https://api.example.com/users/42

带身份验证的 DELETE：

curl -X DELETE https://api.example.com/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN"

带请求体的 DELETE（较少见）：

curl -X DELETE https://api.example.com/users/batch \
  -H "Content-Type: application/json" \
  -d '{"ids": [42, 43, 44]}'

DELETE 并检查响应状态码：

# -w 显示 HTTP 状态码, -o /dev/null 隐藏响应体
curl -X DELETE https://api.example.com/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o /dev/null \
  -w "HTTP Status: %{http_code}\n" \
  -s

身份验证模式

Bearer Token (API 最常用的方式)：

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.example.com/protected

Basic Auth：

# 方案 1: 使用 -u 参数
curl -u username:password https://api.example.com/data

# 方案 2: 使用 Header (base64 编码)
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/data

Header 中的 API Key：

curl -H "X-API-Key: your-api-key-here" \
  https://api.example.com/data

查询参数中的 API Key：

curl "https://api.example.com/data?api_key=your-api-key-here"

真实世界的 API 案例

GitHub API

# 列出你的代码库
curl -H "Authorization: Bearer ghp_YOUR_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/repos

# 创建一个新的代码库
curl -X POST https://api.github.com/user/repos \
  -H "Authorization: Bearer ghp_YOUR_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  -d '{
    "name": "my-new-repo",
    "private": true,
    "description": "Created via cURL"
  }'

OpenAI API

curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "max_tokens": 100
  }'

Stripe API

# 创建一个客户
curl -X POST https://api.stripe.com/v1/customers \
  -u sk_test_YOUR_KEY: \
  -d "email=customer@example.com" \
  -d "name=Jane Doe"

进阶模式

使用 Bash 循环进行失败重试：

MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/data)

  if [ "$HTTP_CODE" -eq 200 ]; then
    echo "Success"
    curl -s https://api.example.com/data
    break
  fi

  RETRY_COUNT=$((RETRY_COUNT + 1))
  echo "Attempt $RETRY_COUNT failed with $HTTP_CODE. Retrying..."
  sleep $((RETRY_COUNT * 2))
done

测量响应时间：

curl -o /dev/null -s -w "
  DNS Lookup:  %{time_namelookup}s
  Connect:     %{time_connect}s
  TLS Setup:   %{time_appconnect}s
  First Byte:  %{time_starttransfer}s
  Total Time:  %{time_total}s
  HTTP Code:   %{http_code}
" https://api.example.com/health

并行发送请求：

# 使用 xargs 进行并行请求
seq 1 10 | xargs -P 5 -I {} curl -s "https://api.example.com/item/{}"

常见坑点及解决方法

问题	原因	解决方法
curl: (60) SSL certificate problem	自签名证书	添加 -k 参数 (仅限开发环境)
JSON 数据未发送	缺少 Content-Type 请求头	添加 -H "Content-Type: application/json"
数据中包含特殊字符	Shell 环境解释冲突	使用单引号包裹或进行转义
响应内容为空	服务器返回 204	使用 -i 查看状态码确认
curl: (7) Failed to connect	端口或主机错误	核实 URL 和端口号

总结

对于任何处理 API 的开发者来说，cURL 都是不可或缺的工具。本指南中的模式涵盖了绝大多数现实场景，从简单的 GET 请求到带文件上传的身份验证 POST 调用。

如果你正在构建使用 AI API 进行图像生成、视频制作或语音合成等任务的应用程序，cURL 是在将 API 调用集成到代码库之前，进行原型制作和测试的绝佳方式。Hypereal AI 为数十种 AI 模型提供 RESTful API 端点，每个端点都能与上述 cURL 模式完美配合。