Go encoding/base64.WithPadding 怎样设置自定义填充字符

我在对接一套把 Base64 尾部填充符改成 ~ 的协议时，最先踩到的坑不是编码本身，而是把“编码字母表”和“填充字符”混成了同一件事。Go 的 encoding/base64 已经提供了 Encoding.WithPadding：它会返回一个使用新填充约定的编码对象，原对象不会被原地改写。

因此，标准 Base64、无填充 Base64 和自定义填充可以保持同一套编解码接口。真正需要记住的是：填充字符必须是合法的单字节值，不能和编码字母表冲突；不需要填充时使用 base64.NoPadding。

先把填充约定和编码对象分开

StdEncoding 使用 RFC 4648 的标准字母表，默认填充字符是 =。WithPadding 复制一个编码对象，再替换它的填充设置，所以可以把结果保存成协议专用变量：

package main

import (
    "encoding/base64"
    "fmt"
)

func main() {
    // 协议约定使用 ~ 作为填充字符，字母表仍然是标准 Base64。
    protocolEncoding := base64.StdEncoding.WithPadding('~')
    encoded := protocolEncoding.EncodeToString([]byte("Go"))
    fmt.Println(encoded)

    // 解码端必须复用同一个填充约定，否则尾部字符无法按协议解释。
    decoded, err := protocolEncoding.DecodeString(encoded)
    if err != nil {
        fmt.Println("解码失败:", err)
        return
    }
    fmt.Println(string(decoded))
}

这里的重点是对象关系：WithPadding 只改变填充策略，不会把 +、/ 等标准字母表替换成 URL 安全字母表。如果协议同时要求 URL 安全字符，应先选择 base64.URLEncoding，再决定是否调用 WithPadding。

用 WithPadding 设置自定义填充字符

自定义填充适合那些明确规定尾部符号的协议。普通编码输入长度不是 3 的倍数时，Base64 输出通常需要填充；更换填充字符只影响这个尾部约定，不会改变前面的编码内容。

package main

import (
    "encoding/base64"
    "fmt"
)

func main() {
    // 这里的编码字母表仍是标准表，只把默认的 = 换成协议字符。
    custom := base64.StdEncoding.WithPadding('.')
    text := custom.EncodeToString([]byte("A"))
    fmt.Println("编码结果:", text)

    // 同一对象负责解码，避免编码端和解码端各自猜测填充规则。
    raw, err := custom.DecodeString(text)
    if err != nil {
        fmt.Println("解码失败:", err)
        return
    }
    fmt.Println("原文:", string(raw))
}

如果服务端协议规定“不允许出现填充”，不要随便挑一个看起来不常见的字符，而应直接使用：

import (
    "encoding/base64"
    "fmt"
)

// NoPadding 表示禁用填充，适合协议明确采用 raw Base64 的场景。
rawEncoding := base64.StdEncoding.WithPadding(base64.NoPadding)
value := rawEncoding.EncodeToString([]byte("A"))
decoded, err := rawEncoding.DecodeString(value)
if err != nil {
    // 解码错误必须向调用方返回，不能把损坏数据当成空字符串。
    fmt.Println("无填充 Base64 解码失败:", err)
}

RawStdEncoding 本质上就是标准字母表配合 NoPadding 的常用预置值。选择预置值还是显式调用 WithPadding，取决于代码是否需要把“协议填充策略”表达得更清楚。

把非法参数挡在创建编码对象之前

WithPadding 对非法填充字符会直接 panic，而不是返回 error。根据 Go 官方实现，以下情况不能作为填充字符：

• 小于 base64.NoPadding 的负值；
• 回车 \r 或换行 \n；
• 大于 0xff 的 rune；
• 已经出现在当前编码字母表中的字符。

package main

import "encoding/base64"

func main() {
    // 这些配置会触发 panic，生产代码应在固定配置进入系统前完成约束检查。
    _ = base64.StdEncoding.WithPadding('+')  // + 已经属于标准字母表
    _ = base64.StdEncoding.WithPadding('\n') // 换行不是合法填充字符
}

如果填充字符来自配置文件，不要直接把未经检查的 rune 交给 WithPadding。更稳妥的做法是先限定它必须是一个 ASCII 字节，并确认它不属于当前编码字母表，再创建长期复用的 *base64.Encoding。

让编码、解码和流式写入保持同一约定

填充策略是编码协议的一部分。最容易出现的线上问题是：编码端使用自定义填充，解码端却使用 StdEncoding；或者短字符串测试正常，换成长数据后尾部填充暴露出差异。

package main

import (
    "bytes"
    "encoding/base64"
    "fmt"
)

func main() {
    // 编解码与流式编码统一引用同一个 Encoding，保证协议设置不漂移。
    enc := base64.StdEncoding.WithPadding('~')
    var out bytes.Buffer
    writer := base64.NewEncoder(enc, &out)

    if _, err := writer.Write([]byte("stream data")); err != nil {
        fmt.Println("写入失败:", err)
        return
    }
    // Close 会刷新最后一个不完整的 Base64 分组，不能省略。
    if err := writer.Close(); err != nil {
        fmt.Println("关闭编码器失败:", err)
        return
    }
    fmt.Println(out.String())
}

可以把最终选择收敛成下面这张速查表：

常见问题

WithPadding 会修改 StdEncoding 吗？

不会。它返回一个新的 *Encoding，原来的 StdEncoding 仍保留默认填充设置。

为什么自定义填充不能使用 +？

因为 + 已经在标准 Base64 字母表中。填充字符必须和字母表区分开，否则解码时无法可靠判断字符角色。

只调用 WithPadding 就能把标准 Base64 变成 URL 安全 Base64 吗？

不能。WithPadding 只负责填充策略；URL 安全字母表应从 URLEncoding 开始，再按协议决定是否去掉填充。

结论很简单：先确定协议的字母表，再确定是否填充，最后让编码端、解码端和流式写入共享同一个 *base64.Encoding。这样既能使用自定义符号，也不会把参数边界问题拖到数据传输阶段。