Go url.QueryEscape 为什么把空格编码成加号

url.QueryEscape 把空格编码成 + 不是错误，而是查询参数长期采用的表单式编码规则：在 application/x-www-form-urlencoded 语义里，空格可以用加号表示。为了避免歧义，原字符串里真正的加号会被编码成 %2B。解码时使用配套的 url.QueryUnescape，它会把 + 还原为空格，把 %2B 还原为加号。

Go 官方文档：https://pkg.go.dev/net/url

URL Standard：https://url.spec.whatwg.org/#application/x-www-form-urlencoded

先看一个最小实验

准备一个空目录，创建 main.go，直接比较“空格”和“字面加号”的结果：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 第一组包含空格；第二组包含真正的加号字符。
    samples := []string{
        "Go language",
        "Go+language",
        "Go language+C++",
    }

    for _, raw := range samples {
        // QueryEscape 只编码一个查询组件，不负责拼接完整查询串。
        escaped := url.QueryEscape(raw)
        fmt.Printf("%q -> %q\n", raw, escaped)
    }
}

运行后，预期可以看到下面的对应关系：

检查点不是“结果里有没有百分号”，而是两种字符有没有被区分：空格使用 +，真正的加号使用 %2B。因此接收方仍能无损恢复原字符串。

为什么空格会变成加号

QueryEscape 的官方说明是“把字符串转义为可安全放入 URL query 的形式”。Go 源码进一步表明，它调用内部的 escape，模式是 encodeQueryComponent；在这个模式下遇到字节 0x20，也就是 ASCII 空格，会直接写入 +。

这与 URL Standard 对 application/x-www-form-urlencoded 的规定一致：使用这套编码集合时，空格采用加号形式。它是 HTML 表单和查询参数生态中保留下来的约定，而不是普通 URL 所有位置都共享的规则。

可以把三种写法理解为三个不同层次：

• +：在查询表单编码中表示空格；
• %20：空格字节的通用百分号编码，很多查询解析器同样接受；
• %2B：字面加号的百分号编码，解码后仍然是 +。

因此，“空格一定只能写成 %20”这个判断并不适用于 QueryEscape。在查询参数上下文里，+ 是正常且可逆的结果。

用 QueryUnescape 检查能否还原

编码函数和解码函数应成对使用。下面把三种输入分别交给 QueryUnescape：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    encoded := []string{
        "Go+language",
        "Go%20language",
        "Go%2Blanguage",
    }

    for _, value := range encoded {
        // QueryUnescape 既处理百分号编码，也把查询中的 + 还原为空格。
        decoded, err := url.QueryUnescape(value)
        if err != nil {
            // 非法的百分号序列必须单独处理，不能忽略错误。
            fmt.Printf("decode %q failed: %v\n", value, err)
            continue
        }
        fmt.Printf("%q -> %q\n", value, decoded)
    }
}

对应结果应分别是 Go language、Go language 和 Go+language。前两种编码都能表示空格，而第三种保留真正的加号。

这也解释了一个常见故障：如果上游直接把字面加号放进查询值，例如 q=C++，再用 QueryUnescape 解析，两个加号会被当成两个空格。正确的查询值应是 C%2B%2B，最好让标准库生成，不要手写替换。

QueryEscape 和 PathEscape 不要混用

URL 的 query 和 path segment 是不同上下文。QueryEscape 面向查询组件，PathEscape 面向单个路径片段，两者对空格和加号的处理不同：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    raw := "Go language+C++"

    // 查询参数中，空格使用 +，字面加号使用 %2B。
    queryPart := url.QueryEscape(raw)

    // 路径片段中，空格使用 %20，而加号可以保留为普通字符。
    pathPart := url.PathEscape(raw)

    fmt.Println("query:", queryPart)
    fmt.Println("path:", pathPart)
}

预期的查询结果是 Go+language%2BC%2B%2B，路径片段结果是 Go%20language+C++。更关键的是解码规则：官方文档明确说明，PathUnescape 与 QueryUnescape 的差别在于它不会把 + 解码为空格。

如果参数要放在 ?q=... 后面，使用查询 API；如果内容是 /users/某个片段 的一部分，使用路径 API。不要为了得到自己偏好的字符串外观而交换这两组函数。

完整查询串优先用 url.Values.Encode

QueryEscape 适合编码一个键或一个值，不适合把整段 q=Go language&page=1 一次性转义。那样会把作为结构分隔符的 = 和 & 也编码掉。

组装多个参数时，让 url.Values 管理键、值和重复参数：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    params := url.Values{}

    // Set 写入单值；Add 可以为同一个键保留多个值。
    params.Set("q", "Go language+C++")
    params.Set("page", "1")
    params.Add("tag", "URL 编码")
    params.Add("tag", "Go 问答")

    // Encode 只编码各个键和值，并保留 & 和 = 的查询结构。
    rawQuery := params.Encode()
    fmt.Println("https://example.com/search?" + rawQuery)
}

这段代码会让空格按查询规则变成加号，让字面加号变成 %2B，并正确生成多个 tag 参数。真实项目中还可以通过 url.URL{RawQuery: params.Encode()} 组合 URL，避免字符串拼接漏掉边界。

再做两个扩展检查

检查中文和 UTF-8

QueryEscape 按 UTF-8 字节做百分号编码。中文会变成多组 %XX，再由 QueryUnescape 恢复。只要两端都按标准 URL 查询编码处理，不需要先手动转成其他字符集。

raw := "Go 空格与加号 +"

// 先编码，再用配套函数解码，检查 UTF-8 内容是否完整回到原值。
encoded := url.QueryEscape(raw)
decoded, err := url.QueryUnescape(encoded)
if err != nil {
    // 实际服务中应把错误返回给调用层或记录上下文。
    log.Fatal(err)
}
fmt.Println(raw == decoded)

检查是否发生重复编码

已经编码过的字符串不能再次交给 QueryEscape。例如 %2B 再编码后，百分号会变成 %25，结果成为 %252B。这通常不是标准库的问题，而是业务层不清楚当前值究竟是“原始值”还是“已编码值”。

raw := "C++"

// 只对原始值编码一次，之后把结果直接放入查询组件。
once := url.QueryEscape(raw)

// 下面仅用于说明重复编码现象，业务代码不应再次转义 once。
twice := url.QueryEscape(once)
fmt.Println(once, twice)

建议在接口边界明确变量含义，例如使用 rawValue、encodedQuery，并规定只有 URL 组装层负责编码。这样能避免多个中间件各自再转义一次。

常见错误速查

相关问题

服务端收到加号时，怎么判断它原来是空格还是加号？

在规范的查询编码中，裸 + 表示空格，字面加号应写成 %2B。如果发送端没有正确编码，接收端无法可靠猜回原意，只能修复发送端协议。

可以把 QueryEscape 结果中的加号替换成 %20 吗？

很多解析器能把两者都解码为空格，但通常没有必要替换。若对接的外部接口明确要求 RFC 3986 风格的 %20，应按该接口规范选择专用编码策略，而不是在所有 Go 查询参数上统一手工替换。

URL.Query().Get 会把加号还原为空格吗？

会。URL.Query 解析查询串时使用查询解码语义，因此裸加号会作为空格处理，%2B 才会得到字面加号。

结论：QueryEscape 输出加号，是查询参数编码的正常行为。空格、+ 与 %2B 必须按上下文理解；完整查询用 url.Values.Encode，路径片段用 PathEscape，不要靠手工替换字符拼 URL。