cURL 命令生成器与构建工具

什么是 curl 命令？

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

核心功能

curl 替代工具与 HTTP 客户端

curl 命令示例

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

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

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

如何构建 curl 命令

1. 1

   选择 HTTP 方法

   选择 GET、POST、PUT、PATCH、DELETE、HEAD 或 OPTIONS。curl 默认为 GET；选择 POST 或其他动词会在生成的命令中添加 `-X METHOD`。或点击预设芯片，一键设置方法和匹配的请求体。

2. 2

   输入 URL 和查询参数

   输入请求 URL（如 `https://api.example.com/users`）。以键值对形式添加查询参数，工具会自动进行 URL 编码并将 `?key=value&…` 追加到 URL——无需手动编码。

3. 3

   添加请求头和认证

   以键值对形式添加请求头，然后选择认证方案：无、Bearer 令牌、Basic（用户名/密码）或自定义 API 密钥请求头。以服务器期望的精确格式生成正确的 `Authorization` 或自定义请求头。

4. 4

   设置请求体

   对于 POST/PUT/PATCH，选择请求体类型：粘贴原始 JSON（自动为您添加 `Content-Type` 请求头）、构建 urlencoded 表单字段，或组装 multipart 上传并通过 `@` 前缀将任意字段切换为文件。

5. 5

   切换选项

   按需开启所需标志——跟随重定向（`-L`）、不安全 TLS（`-k`）、详细模式（`-v`）、包含响应头（`-i`）、压缩（`--compressed`）、输出到文件（`-o`）、连接超时或代理（`-x`）。每次切换都会实时更新命令。

6. 6

   复制、导出或重置

   复制已完成的命令，导出为 .sh 脚本下载，或重置以清空表单。复制前可使用多行切换在单行和反斜杠续行输出之间切换。

常见 curl 错误

# Intended a PATCH, but -d alone implies POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# Set the verb explicitly
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# Server sees urlencoded, not JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Declare the JSON content type
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name gets expanded by the shell to empty string
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Single quotes send the body literally
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d makes this a POST, not a GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# Query string on the URL keeps it a GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — backslash is not a continuation char
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — one line, or use ^ to continue
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# Space splits the argument — curl sees two args
curl https://api.example.com/search?q=hello world

# Encode the space (or quote the whole URL)
curl 'https://api.example.com/search?q=hello%20world'

常见使用场景

REST API 测试

无需离开终端，直接针对 REST 端点构建并发送请求：设置方法、粘贴 Bearer 令牌、发送 JSON 请求体，读取响应。在编写客户端代码之前，这是确认 API 行为的最快方式。

从文档重现请求

API 文档展示端点和参数，但很少提供完整的可直接运行的命令。在此填写方法、URL、请求头和认证，即可获得可直接运行的 curl 命令——不再为引号规则或缺少 `Content-Type` 请求头而烦恼。

CI/CD 冒烟测试脚本

为健康检查或部署后冒烟测试生成 curl 命令，然后导出为 .sh 文件放入流水线。添加 `--connect-timeout` 和 `--max-time` 以防止挂起的端点阻塞构建，并使用 `-w` 检查状态码。

文件上传与下载

组装带有 `-F field=@file` 的 `multipart/form-data` 上传，或构建跟随重定向到 CDN 的 `-L -o filename` 下载。对于复杂的文件名或查询值，可先使用我们的 URL 编码器 进行编码。

Webhook 调试

通过 POST 提供商发送的相同 JSON 请求体（含正确的签名和 `Content-Type` 请求头）来重放 Webhook 载荷。在本地重现确切的请求，以调试处理程序拒绝的原因。

可复现的 Bug 报告

在 Bug 报告或 PR 中粘贴一条自包含的 curl 命令，任何人都可以重现确切的请求——包含方法、请求头、认证占位符和请求体。远比用文字描述请求清晰。

学习 curl 标志

观察每个表单选项如何映射到真实的标志——选择 Basic 认证时看 `-u` 出现，添加 JSON 请求体时看 `Content-Type` 请求头自动附加。一种直观学习语法的方式，配合我们的 curl 速查表 使用效果更佳。

为代码转换准备请求

先以 curl 构建并验证请求，然后将其转换为应用程序的 HTTP 客户端代码。即将推出的"转换"标签页将把粘贴的 curl 命令转换为 fetch、requests、Go、PHP、Ruby 和 Node.js——从一条已知有效的 curl 命令开始。

curl 标志与语法参考

Shell 引号与转义

工具使用单引号包裹值，这是 POSIX Shell 中最安全的形式，因为单引号字符串内的任何内容都不会被展开。值中的字面单引号以 `'\''` 序列输出（关闭引号、转义引号、重新开启引号）。在 `cmd.exe` 中请切换为双引号；Git Bash 和 WSL 可直接运行生成的单引号命令，无需修改。

-d 与 --data-raw 与 --data-binary

`-d`/`--data` 发送请求体时会去除换行符和回车符——对于 `key=value` 键值对没问题，但对于多行内容会造成损失。`--data-raw` 与之相同，但不会将开头的 `@` 视为文件名。`--data-binary` 完全按原样发送字节（使用 `@file` 上传原始文件内容）。这三者均默认使用 POST，除非覆盖方法。

Multipart（-F）与 URL 编码（-d）

`-F field=value` 生成带有自动边界的 `multipart/form-data`——文件上传（`-F file=@path`）和混合文件/文本表单必须使用此方式。`-d field=value` 生成 `application/x-www-form-urlencoded`，即以 `&` 连接的单个字符串。对于 multipart，切勿手动设置 `Content-Type`；curl 会自行计算边界并设置请求头。

认证请求头编码

Bearer 认证按原样发送 `Authorization: Bearer `（RFC 6750）。通过 `-u user:pass` 的 Basic 认证会将凭据 Base64 编码后放入 `Authorization: Basic ` 中传输——这是编码而非加密，请务必使用 HTTPS。API 密钥则是服务要求的任意自定义请求头，例如 `X-API-Key: `。

查询字符串编码

构建器中添加的查询参数会进行百分比编码，并以 `?key=value&key2=value2` 的形式追加。保留字符（空格、`&`、`=`、`#`）会被转义以确保 URL 有效。对于必须编码的请求体字段，curl 自带的 `--data-urlencode` 可在请求时处理编码。

重定向行为（-L）

不带 `-L` 时，curl 打印 301/302 响应后停止。带 `-L` 时，它会跟随 `Location` 请求头到最终 URL。注意：当重定向跨越不同主机时，curl 会丢弃 `Authorization` 请求头（这是安全默认行为）；仅在充分了解其影响的情况下才使用 `--location-trusted`。

压缩响应

`--compressed` 添加 `Accept-Encoding` 请求头，声明支持 gzip/deflate/brotli，并透明地解压响应，节省带宽。解码后的响应体与未压缩请求完全相同——这纯粹是传输优化，在大多数 API 调用中可安全启用。

输出：-o 与 -O

`-o filename` 将响应体写入您命名的文件；`-O` 使用 URL 路径中的远程文件名保存。两者均会抑制正常的标准输出。与 `-L` 结合使用，可在写入文件前将重定向解析到真实资源。

curl 请求最佳实践

切勿在共享命令中硬编码密钥

粘贴到 PR、工单或聊天中的 curl 命令会被他人看到并被工具索引。请将令牌和密码替换为占位符（`YOUR_TOKEN`）或引用环境变量（`-H "Authorization: Bearer $API_TOKEN"`）。对于长凭据，curl 可通过 `-H @headerfile` 从文件读取请求头，这样密钥就不会出现在 Shell 历史记录中。

对二进制载荷优先使用 --data-binary @file

当请求体是字节内容重要的文件时——图片、已签名的载荷、空白字符有意义的 JSON——请使用 `--data-binary @file` 而非 `-d @file`。普通的 `-d` 会去除换行符和回车符，静默地破坏二进制和多行内容。`--data-binary` 会按磁盘上的原样发送文件。

为请求头值加引号

始终用引号包裹 `-H` 的值：`-H 'Content-Type: application/json'`。不加引号时，冒号后的空格会分割参数，curl 会看到格式错误的请求头。单引号还可以防止 Shell 展开值中的 `$`、`*` 和其他特殊字符——这正是此工具默认生成的格式。

使用 --compressed 节省带宽

在 API 调用和下载中添加 `--compressed`，以请求 gzip/brotli 编码并让 curl 透明解压。对于 JSON 密集型 API，这可以将传输大小减少 70–90%，而您看到的响应不变——对于频繁轮询端点的脚本来说是免费的性能提升。

在脚本中设置超时

在任何自动化上下文中，添加 `--connect-timeout` 和 `--max-time`，防止缓慢或挂起的端点永久阻塞流水线。带有 `--max-time 10` 的健康检查可快速失败并让 CI 继续运行。与 `--retry N` 配合使用，以应对瞬时网络抖动而无需立即放弃。

自动化前先用 -v 验证

在将 curl 命令放入脚本或定时任务之前，先带 `-v` 运行一次，查看确切的请求行、请求头和 TLS 握手。这是发现错误方法、缺少 `Content-Type` 或认证请求头未附加的最快方式——交互式调试，然后在生产中移除 `-v`。

常见问题