5月28日 02:37

cURL 如何处理 URL 编码和特殊字符？

在 cURL 中处理 URL 编码和特殊字符是日常请求中绕不开的问题——查询参数里的空格、中文、& 和 = 都可能在传输中被误解析。理解 cURL 提供的编码机制，以及何时需要手动编码，能避免大量调试时间。

URL 编码的核心规则

URL 编码（Percent Encoding）将非安全字符转换为 %XX 格式，XX 是字符 UTF-8 字节的十六进制表示。RFC 3986 规定，只有字母、数字和 -_.~ 属于无需编码的"未保留字符"。

bash
# 常见字符的编码映射
空格     -> %20
&        -> %26
=        -> %3D
+        -> %2B
%        -> %25
#        -> %23
中文     -> %E4%B8%AD%E6%96%87

需要区分两种编码场景：URL 路径编码遵循 RFC 3986，空格编码为 %20；表单提交编码（application/x-www-form-urlencoded）遵循 HTML 规范，空格编码为 +。cURL 的 --data-urlencode 使用的就是表单编码规则。

--data-urlencode 的四种语法

--data-urlencode 是 cURL 处理编码的主力参数，但它支持多种写法，行为各不相同：

bash
# 1. key=value：对 value 部分 URL 编码
curl --data-urlencode "name=hello world" https://api.example.com
# 发送：name=hello+world（value 编码，key 不编码）

# 2. =value：对整个 value 编码，不带 key
curl --data-urlencode "=hello world" https://api.example.com
# 发送：hello+world

# 3. key@filename：读取文件内容作为 value 并编码
curl --data-urlencode "content@/tmp/payload.txt" https://api.example.com
# 文件内容会被 URL 编码后作为 content 的值

# 4. @filename：读取文件内容并编码，不带 key
curl --data-urlencode "@/tmp/raw_data.txt" https://api.example.com
# 文件内容整体编码后发送

面试追问：为什么 --data-urlencode "name=value" 只编码 value 而不编码 key？因为 key 是开发者可控的固定字符串，通常不含特殊字符；而 value 来自用户输入，不可控，必须编码。

GET 请求中的编码：-G 配合 --data-urlencode

--data-urlencode 默认以 POST 方式发送数据。加上 -G（或 --get）后，数据会被追加到 URL 查询字符串中：

bash
# 构建带编码的 GET 请求
curl -G https://api.example.com/search \
  --data-urlencode "q=hello world" \
  --data-urlencode "category=技术&编程"
# 实际请求：https://api.example.com/search?q=hello+world&category=%E6%8A%80%E6%9C%AF%26%E7%BC%96%E7%A8%8B

如果不加 -G，同样的命令会把数据放进请求体，变成 POST 请求——这是 cURL 新手最常犯的错误之一。

手动编码：当 --data-urlencode 不够用时

有些场景下 --data-urlencode 无法覆盖需求，比如 URL 路径中包含中文、需要对整个 URL 做编码处理等。

bash
# 使用 Python 编码（最通用）
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('hello world & 中文'))")
curl "https://api.example.com/search?q=$ENCODED"

# 使用 jq 编码（适合管道操作）
ENCODED=$(jq -nr --arg s 'hello world' '$s | @uri')
curl "https://api.example.com/search?q=$ENCODED"

# 利用 cURL 自身做编码（巧妙但可读性差）
encode() {
  local data="$(curl -s -o /dev/null -w '%{url_effective}' --get --data-urlencode "$1" "")"
  echo "${data#/?}"
}
ENCODED=$(encode "hello world & 中文")
curl "https://api.example.com/search?q=$ENCODED"

双编码陷阱

对已经编码过的字符串再次编码，会产生双重编码（double-encoding），这是最难排查的一类 bug：

bash
# 正确：只编码一次
curl -G https://api.example.com/search \
  --data-urlencode "q=hello%20world"
# 服务端收到：q=hello%20world → 解码为 "hello world"

# 错误：--data-urlencode 又对 %20 做了一次编码
# 结果 %20 变成了 %2520
# 服务端收到：q=hello%2520world → 解码为 "hello%20world"

避免方法：如果一个值已经是编码后的，不要再通过 --data-urlencode 处理。用 -d 代替，或者确保输入始终是未编码的原始值。

bash
# 如果值已经是编码后的，用 -d 直接发送
curl -G https://api.example.com/search \
  -d "q=hello%20world"

# 如果值是原始值，用 --data-urlencode
curl -G https://api.example.com/search \
  --data-urlencode "q=hello world"

查询参数中 & 和 = 的歧义

URL 中 & 是参数分隔符，= 是键值分隔符。当参数值本身包含这些字符时，不加编码会导致参数解析错误：

bash
# 错误：& 被误认为参数分隔符
curl "https://api.example.com/search?q=foo&bar"
# 服务端理解为两个参数：q=foo 和 bar（无值）

# 正确方式一：手动编码
curl "https://api.example.com/search?q=foo%26bar"

# 正确方式二：用 --data-urlencode 自动处理
curl -G https://api.example.com/search \
  --data-urlencode "q=foo&bar"

路径中的特殊字符

URL 路径（? 之前的部分）中的特殊字符处理与查询参数不同。cURL 默认会对路径中的部分字符做处理：

bash
# 路径中的空格需要编码
curl "https://api.example.com/files/my%20document.pdf"

# 路径中的中文需要编码
curl "https://api.example.com/files/%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6.pdf"

# --path-as-is：阻止 cURL 对路径做任何处理（保留原始路径）
# 不加此参数时，cURL 会把 /../ 和 /./ 规范化
curl --path-as-is "https://api.example.com/../secret.txt"

JSON 请求体中的特殊字符

JSON 请求体不走 URL 编码，但有自己的转义规则——双引号、反斜杠、控制字符需要转义：

bash
# 直接写 JSON 时需要手动转义
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","bio":"Line1\nLine2\tTabbed"}'

# 用 jq 生成 JSON，自动处理转义（推荐）
jq -n '{name: "张三", bio: "Line1\nLine2"}' | \
  curl -X POST https://api.example.com/users \
    -H "Content-Type: application/json" \
    -d @-

表单提交的混合编码

实际开发中经常需要同时发送已编码字段和待编码字段：

bash
curl -X POST https://api.example.com/submit \
  -d "id=123&status=active" \
  --data-urlencode "content=Special chars: & = ?"

-d 和 --data-urlencode 可以混用。cURL 会将所有数据合并为一条请求体，-d 的部分原样发送，--data-urlencode 的部分自动编码。

调试编码问题的方法

编码问题的排查关键在于确认"实际发送的内容到底是什么"：

bash
# 方法一：用 -v 查看完整请求（包含编码后的 URL）
curl -v -G https://api.example.com/search \
  --data-urlencode "q=hello world"

# 方法二：用 --trace-ascii 把完整请求写入文件
curl --trace-ascii /tmp/trace.log -G https://api.example.com/search \
  --data-urlencode "q=hello world"
# 然后查看 trace.log 确认实际 URL

# 方法三：用 -w 输出编码后的实际 URL
curl -s -o /dev/null -w '%{url_effective}\n' -G https://api.example.com/search \
  --data-urlencode "q=hello world"
# 输出：https://api.example.com/search?q=hello+world

实战脚本

bash
#!/bin/bash
# URL 编码处理封装

# 编码函数（依赖 python3）
urlencode() {
  python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$1"
}

API_BASE="https://api.example.com/v1"

# GET 请求：自动编码查询参数
curl -G "${API_BASE}/search" \
  --data-urlencode "q=hello world & 中文" \
  -H "Accept: application/json"

# POST 请求：混合编码字段
curl -X POST "${API_BASE}/submit" \
  -d "type=article" \
  --data-urlencode "title=深入理解 cURL 编码" \
  --data-urlencode "content=包含 & 和 = 的内容"

# 路径中含中文：手动编码路径部分
ENCODED_NAME=$(urlencode "中文文件")
curl "${API_BASE}/files/${ENCODED_NAME}.pdf"

面试中常被追问的关键区别：--data-urlencode 编码的是 value 部分，-d 原样发送；表单编码空格变 +，路径编码空格变 %20；已编码的值不要再过 --data-urlencode，否则会双编码。掌握这三条，cURL 的编码问题基本不会踩坑。

标签：cURL