Go 中的 Base64 解码：完整指南

API 响应里藏着一长串字符串，它假装自己是一个值，实际上却是一个文件、一个令牌、一张图片，或者一条来自比你大三岁的系统的消息。在你的日志行、数据库行和 JSON 载荷的某个角落，base64 字符串无处不在：标准的 64 字符字母表，有时带着加号和斜杠，有时带着连字符和下划线，偶尔还有两个等号停在末尾，像签名一样。

本站首页已经把格式本身讲清楚了：64 个可打印字符，每个携带 6 比特，每三个输入字节对应四个字符，再加填充收尾。所以这篇文章直接切入工作中有趣决策所在的那一半：在 Go 里打开这些字符串。好消息是，Go 是做这件事的好地方。一个标准库包，零依赖，一个默认严格但对换行宽容的解码器，还有能指出究竟哪个字节出了错的错误信息。

Go 自带了什么

你需要的一切已经在标准库里了。这个包叫 encoding/base64，它的源文件还戴着 2009 年、也就是这门语言出生那一年的版权头，没有需要启用的扩展，没有需要拉取的模块，没有需要拨动的开关。只要 go version 能在你的机器上打印出任何东西，你就已经拥有了整套工具。

截至本文写作时，最新的发行版是 Go 1.27.1，发布于 2026 年 9 月 1 日，另一条受支持的线是 Go 1.26（目前是 1.26.8）。两条线上的 base64 API 完全一致，而且得益于 Go 1 兼容性承诺，一个今天会解码 base64 的程序，在未来的每个发行版上都会做完全相同的事。Go 本身可以从 go.dev/dl 的官方压缩包获取（类似 go1.27.1.linux-amd64.tar.gz，解压到 /usr/local），从你的发行版包管理器安装（基于 Ubuntu 的系统上是 sudo apt install golang-go），或者通过 golang.org/dl 封装器，如果你喜欢让几个 Go 版本并排共存。

Go 装好之后，go doc encoding/base64 会用易读的栏宽打印出整个 API，这是刷新记忆最快的方式。这篇文章用到的唯一附加包是 golang.org/x/text，用来处理遗留字符集，安装命令是 go get golang.org/x/text。它只出现一次，在自己专属的一节里，其余全是纯标准库。

你的第一次解码

Go 里百分之九十的解码生活，就是 Encoding 类型上的一个方法：

func (enc *Encoding) DecodeString(s string) ([]byte, error)

给它一个 base64 字符串，它还给你这个字符串代表的字节；输入捣乱时，外加一个错误：

package main

import (
  "encoding/base64"
  "fmt"
)

func main() {
  decoded, err := base64.StdEncoding.DecodeString("TWFu")
  if err != nil {
    fmt.Println("decode failed:", err)
    return
  }
  fmt.Println(string(decoded)) // Man
}

那个签名有两点值得背下来。第一，结果是 []byte，不是字符串，因为你拆开的字节可以是完全合法的 base64，同时也是彻底不可读的文本：一个 PNG 头、一个压缩归档、一个二进制协议。只有当你知道载荷是文本时，才用 string(...) 包一层。第二，这个方法永远返回两个值。错误为 nil 意味着字符串是干净的 base64；错误非 nil 意味着输入在某个地方坏了，而你收到的字节切片可能是一个部分结果，而不是空的。下面错误那一节会让你看到这种行为的两个侧面。

四个解码器，一个问题：哪个字母表？

Go 自带四个现成的 Encoding 值，选对哪一个，是每次解码的第一个真正的决策。下面这张表就是座位图：

最快的选择方式是看数据本身。包含 + 或 / 的字符串只可能是标准字母表字符串，所以它需要两个 Std 解码器之一。包含 - 或 _ 的字符串是 RFC 4648 的 URL 安全变体，所以它需要两个 URL 解码器之一。然后看尾部：末尾有 = 字符意味着带填充变体，没有则意味着 Raw 变体。选错的感受是这样的：

decoded, err := base64.StdEncoding.DecodeString("P29_")
// err: illegal base64 data at input byte 3
// 下划线不在标准字母表里，所以
// 解码器停在它不认识的最后一个字符处
decoded, err = base64.URLEncoding.DecodeString("P29_")
// decoded 是三个字节 0x3f 0x6f 0x7f，err 为 nil

如果你要解码的数据来自一个定义了自己 64 字符字母表的生产者，base64.NewEncoding("...64 chars...") 可以为你构建一个解码器。字母表必须恰好是 64 个唯一的字节值，而且不能包含换行 - 否则函数会 panic - 文档要求字母表排除填充字符，函数却不强制这一点 - 包含 '=' 的字母表会被接受，且不会 panic。日常工作中你很少需要它，但它在那里，而且它是解码私有方案的唯一途径。

宽容度问题：Go 接受什么输入？

每个 base64 解码器都要做一个让人不太舒服的决策：它愿意吞下多少垃圾？Go 的答案是一条精心划定的线。宽容的一面：解码器跳过输入中任何位置的回车和换行，所以一个被邮件客户端或 PEM 工具折成多行的字符串，不需要任何预处理就能解码：

decoded, err := base64.StdEncoding.DecodeString("T\nW\nF\r\nu")
// decoded 是 "Man"，err 为 nil
// 字符串里的每一个 \r 和 \n 都被直接忽略了

严格的一面：其他一切都免谈。一个空格、一个制表符、一个从 PDF 复制来的零宽字符、一个从头部溜进来的冒号：解码器一旦遇到字母表之外且不是换行的字符，就停下来并报出偏移量。而且它会保留已经解出来的部分：

decoded, err := base64.StdEncoding.DecodeString("TWFu junk")
// decoded 是 "Man"（空格之前的部分），
// err 是：illegal base64 data at input byte 4

这个组合会让人吃惊：一次失败的解码，仍然可能交给你一个可用的半成品。这算特性还是隐患，取决于你；关键在于，err == nil 是数据完整的唯一条件。

填充有它自己的规则，而且带填充变体和 raw 变体之间并不相同。带填充的解码器按组工作：一组要么是四个真实字符，要么是两个真实字符加 ==。单独一个字符永远不构成完整的一组，所以 "T" 会失败，"TWF" 也会失败，因为三个字符需要一个缺失的填充符号。raw 解码器丢掉了填充要求，但它们仍然不接受那种一组四个字符缺了三个的长度，所以 "T" 在那里同样失败，而 "TW" 会痛痛快快地解码成一个字节。

base64.StdEncoding.DecodeString("T")        // 在第 0 个输入字节处报错
base64.StdEncoding.DecodeString("TWF")      // 在第 0 个输入字节处报错
base64.RawStdEncoding.DecodeString("TW")    // 1 个字节，无错误
base64.StdEncoding.DecodeString("TWFu====") // "Man" 外加第 4 字节处的错误

还有一个性格开关：Strict()，Go 1.8 加入。严格模式下，解码器强制执行 RFC 4648 第 3.5 节的规范形式：最后一组未使用的末尾比特必须是零。普通模式不在乎，因为那些比特反正永远不会被用到，所以 "Qm==" 会解码为字节 B 而毫无怨言。严格模式则会拒绝它：

decoded, err := base64.StdEncoding.DecodeString("Qm==")
// decoded 是 "B"，err 为 nil（末尾比特被丢弃了）
decoded, err = base64.StdEncoding.Strict().DecodeString("Qm==")
// err 是：illegal base64 data at input byte 2

注意，即使在严格模式下，换行仍然会被跳过，文档也指出了这一点。当你所用的协议在乎规范编码时，或者你想拒绝敷衍的生产者、而不是默默吸收它们那些比特时，就用 Strict()。

会告诉你出在哪里的错误

这个包里的每次失败，都以一个具体、可检查的值的形式到来。当输入包含字母表不认识的东西，或者填充不对时，解码器返回 base64.CorruptInputError，它的消息包含问题所在的字节偏移量：

type CorruptInputError int64

func (e CorruptInputError) Error() string {
  return "illegal base64 data at input byte " + strconv.FormatInt(int64(e), 10)
}

这个偏移量，就是"某处失败了"和"这个 900 千字节字符串的第 4102 个字符，是一个从剪贴板溜进来的制表符"之间的区别。用惯用的 Go 写法捕获它：

package main

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

func main() {
  _, err := base64.StdEncoding.DecodeString("TWF$")
  var corrupt base64.CorruptInputError
  if errors.As(err, &corrupt) {
    fmt.Printf("bad byte at offset %d: %v\n", int(corrupt), err)
    // bad byte at offset 3: illegal base64 data at input byte 3
    return
  }
  fmt.Println("not a corrupt-input error:", err)
}

下面这张症状表，对应那些最让人困惑的输入：

一个实用的技巧：当解码在生产环境失败时，把偏移量及其附近的一小段窗口记进日志。百分之九十的情况下，那个"损坏"的字节是传输层、剪贴板或 PDF 阅读器偷偷塞进字符串的空白字符，修复方式是修剪或剥离，而不是重新设计。

打开文件

Base64 文件就是装着 base64 的文本文件，所以 Go 常用的文件工具都适用。对于能轻松装进内存的文件，全部读出来，再解码字符串：

package main

import (
  "encoding/base64"
  "fmt"
  "io"
  "os"
)

func main() {
  f, err := os.Open("payload.b64")
  if err != nil {
    fmt.Println("open failed:", err)
    return
  }
  defer f.Close()

  raw, err := io.ReadAll(f)
  if err != nil {
    fmt.Println("read failed:", err)
    return
  }
  decoded, err := base64.StdEncoding.DecodeString(string(raw))
  if err != nil {
    fmt.Println("decode failed:", err)
    return
  }
  fmt.Println("decoded", len(decoded), "bytes")
}

对大文件来说，更好的模式是流式处理，它用的是这个包 API 的另一半：NewDecoder 把任何 io.Reader 包成一个 base64 解码读取器，这样你就可以把文件接到文件，而永远不必把整个载荷握在内存里：

in, err := os.Open("payload.b64")
if err != nil {
  panic(err)
}
defer in.Close()

dec := base64.NewDecoder(base64.StdEncoding, in)
out, err := os.Create("payload.bin")
if err != nil {
  panic(err)
}
defer out.Close()

written, err := io.Copy(out, dec)
if err != nil {
  panic(err)
}
fmt.Println("wrote", written, "bytes")

当你想避免 DecodeString 的那次额外分配时，还有一个中间选项：Decode 写进一个由你控制的目的地缓冲区。用 DecodedLen 给它定尺寸，它返回给定输入长度对应的最大输出字节数：

raw, err := os.ReadFile("payload.b64")
if err != nil {
  panic(err)
}
buf := make([]byte, base64.StdEncoding.DecodedLen(len(raw)))
n, err := base64.StdEncoding.Decode(buf, raw)
if err != nil {
  panic(err)
}
data := buf[:n] // 实际解码出的大小
fmt.Println(len(data), "bytes")

不过对最后一个要小心：Decode 信任你能给缓冲区定好尺寸。如果太小，这个方法不会返回错误；它会以索引越界的方式 panic。DecodedLen 才是该用的数字，而不是 len(raw)。

Go 版 base64 命令行

Unix 系统随 coreutils 附带一个 base64 工具，而 Go 不附带等价的二进制。Go 世界里惯用的答案，不是你去安装的一个包，而是你拥有的一个程序：一个围绕 encoding/base64、flag 包和标准输入构建的小型命令行工具。下面是一个完整的，大约四十行，解码任何被管道送进来的东西，并把原始字节写出去：

package main

import (
  "encoding/base64"
  "flag"
  "fmt"
  "io"
  "os"
)

func main() {
  urlSafe := flag.Bool("url", false, "use the URL-safe alphabet")
  flag.Parse()

  enc := base64.StdEncoding
  if *urlSafe {
    enc = base64.URLEncoding
  }

  raw, err := io.ReadAll(os.Stdin)
  if err != nil {
    fmt.Fprintln(os.Stderr, "read failed:", err)
    os.Exit(1)
  }
  decoded, err := enc.DecodeString(string(raw))
  if err != nil {
    fmt.Fprintln(os.Stderr, "decode failed:", err)
    os.Exit(1)
  }
  os.Stdout.Write(decoded)
}

用 go build -o b64 . 构建一次，它就变成一个跨平台解码器，可以塞进 Makefile、CI 流水线或 shell 函数：printf 'TWFu' | ./b64 打印 Man，而 ./b64 -url < token.b64 > token.bin 把一个 URL 安全令牌解包成一个文件。这个设计有两个特性值得注意。因为它在解码前读完全部 stdin，被折行、夹着换行的输入也能正常解码，要归功于解码器的换行宽容。又因为它在输入有问题时以状态 1 退出，并把抱怨写到 stderr，所以它表现得像管道里的一个工具，而不是一个会道歉的脚本。这就是 Go CLI 的全部艺术：一个包，一个标志，标准输入，标准输出，外加一个退出码。

URL 安全解码

URL 安全变体存在的原因，是标准字母表和 URL 的语法打架：+ 在查询字符串里常被读成空格，/ 会开启一个新的路径段，所以嵌在 URL 里的标准 base64 字符串必须逐字符做百分号转义，解析慢，读着也丑。RFC 4648 的替代字母表把 + 和 / 换成 - 和 _，这两者在 URL 路径、查询和文件名里都可以合法地不转义。

在 Go 里，切换只是一个不同的解码器变量。如果你的数据是 URL 安全且带填充的，用 URLEncoding；如果是 URL 安全且无填充的，用 RawURLEncoding。经典场景是活在 URL 或文件名里的标识符：

decoded, err := base64.RawURLEncoding.DecodeString("-w9n")
// decoded 是三个字节 0xfb 0x0f 0x67
// 连字符和下划线属于 URL 安全字母表，
// 所以 StdEncoding 会失败的地方，RawURLEncoding 能处理

在真实的 Go 代码里你会在哪里遇到它：JWT 段（下一节讲）、系统生成并存进 URL 的不透明标识符、不能搞垮 web 服务器或云对象存储的文件名，以及任何在文档里承诺了 "base64url" 的 API。一个警告：URL 安全是生产者和消费者之间的约定，不是数据的属性。如果字符串包含 + 或 /，它就不是 URL 安全，没有商量余地，用 URL 解码器重试多少次都没用。先看字符，再挑解码器。

窥探 JWT 内部

一个 JSON Web Token 是三段用点号分隔的 base64url 段：头部、装着声明的载荷、签名，任何一段都没有填充。这让 JWT 成为你在 Go 里最常解码的东西之一，而且头部和载荷不用任何密钥就能读，这一点无论对调试还是安全审查都值得记住：

package main

import (
  "encoding/base64"
  "fmt"
  "log"
  "strings"
)

func main() {
  token := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiR28gRGV2ZWxvcGVyIiwic3ViIjoiMTIzNDU2Nzg5MCJ9.NwJQAKfJpMJQuK0gEECtXtO8cIoFnDp0ovXyl7dY1BQ"
  parts := strings.Split(token, ".")
  if len(parts) != 3 {
    log.Fatal("not a JWT: expected three dot-separated parts")
  }
  for i, name := range []string{"header", "payload"} {
    plain, err := base64.RawURLEncoding.DecodeString(parts[i])
    if err != nil {
      log.Fatalf("bad %s: %v", name, err)
    }
    fmt.Printf("%s: %s\n", name, plain)
  }
  // header:  {"alg":"HS256","typ":"JWT"}
  // payload: {"name":"Go Developer","sub":"1234567890"}
}

注意解码器的选择：RawURLEncoding，不是 StdEncoding。JWT 段使用 URL 安全字母表且不带填充，长度比四的倍数少一或二的那段，会让带填充的解码器在最后一刻失败，而那种错误很让人摸不着头脑。签名段没有密钥就读不了，而且你不应该只凭载荷就信任任何东西，因为没有什么能阻止客户端伪造前两段。当你需要验证时，用一个维护中的库。事实标准是 github.com/golang-jwt/jwt/v5（用 go get github.com/golang-jwt/jwt/v5 安装）：

package main

import (
  "fmt"
  "log"

  "github.com/golang-jwt/jwt/v5"
)

func main() {
  secret := []byte("hmac-secret")
  token := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiR28gRGV2ZWxvcGVyIiwic3ViIjoiMTIzNDU2Nzg5MCJ9.NwJQAKfJpMJQuK0gEECtXtO8cIoFnDp0ovXyl7dY1BQ"

  parsed, err := jwt.Parse(token, func(t *jwt.Token) (any, error) {
    if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
      return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
    }
    return secret, nil
  })
  if err != nil {
    log.Fatal("token rejected:", err)
  }
  claims, _ := parsed.Claims.(jwt.MapClaims)
  fmt.Println("subject:", claims["sub"])
}

这个库有两个细节值得知道。第一，这三个段的 base64url 编码和解码都在库内部处理，所以你签名或验证时根本不会直接碰 encoding/base64。第二，v5 库拒绝 alg=none 的令牌，除非你明确传入它的 UnsafeAllowNoneSignatureType 常量，这保护你免于犯经典的"接受了未签名令牌"错误。

Data URL

Data URL 是一种载荷就是数据本身的 URL。它的语法来自 RFC 2397：data:[mediatype][;base64],data：一个可选的媒体类型，一个可选的 ;base64 标志，一个逗号，然后是内容。当 ;base64 标志存在时，内容是标准 base64，这就是 data URL 和这篇文章共享一节的原因。浏览器用它们把图片和字体直接嵌进 HTML 和 CSS，这样页面就少发一个请求：

<img src="data:image/png;base64,iVBORw0KGgo=" alt="pixel">

Go 的标准库没有 data URL 助手，但这个格式简单到可以用 strings 手工解析，大多数 Go 程序就是这么做的：

package main

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

func main() {
  url := "data:image/png;base64,iVBORw0KGgo="
  if !strings.HasPrefix(url, "data:") {
    fmt.Println("not a data URL")
    return
  }
  rest := url[len("data:"):]
  comma := strings.Index(rest, ",")
  if comma == -1 {
    fmt.Println("missing comma")
    return
  }
  meta := rest[:comma]      // image/png;base64
  encoded := rest[comma+1:] // iVBORw0KGgo=
  if !strings.HasSuffix(meta, ";base64") {
    fmt.Println("this variant is percent-encoded, not base64")
    return
  }
  mediaType := strings.TrimSuffix(meta, ";base64")
  decoded, err := base64.StdEncoding.DecodeString(encoded)
  if err != nil {
    fmt.Println("decode failed:", err)
    return
  }
  fmt.Println(mediaType, "carries", len(decoded), "bytes")
}

有三个陷阱要记住。第一，;base64 标志是可选的，没有它时载荷是百分号编码的 ASCII，而不是 base64，所以调用解码器之前先检查后缀。第二，媒体类型被省略时，默认值是 text/plain;charset=US-ASCII，这对图片几乎无关紧要，但会让解析其他内容的人吃惊。第三，data URL 是一个小载荷技巧：RFC 自己就说这个方案只对短值有用，而 base64 33% 的体积膨胀会让一个 500 千字节的 logo 变成一个 666 千字节、粘在你 HTML 里的字符串，不可缓存，无法分享。用它来放图标和缩略图，不要放视频。

HTTP 与 API 工作

Go web 服务里最常见的单一解码，就是 JSON 正文里的字段：一个上传表单、一个 API 响应或一个 webhook 递给你一个其实是文件的字符串。先反序列化到结构体，然后解码这个字段：

package main

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

type payload struct {
  Avatar string `json:"avatar"`
}

func main() {
  body := []byte(`{"avatar": "iVBORw0KGgo="}`)
  var p payload
  if err := json.Unmarshal(body, &p); err != nil {
    fmt.Println("bad JSON:", err)
    return
  }
  img, err := base64.StdEncoding.DecodeString(p.Avatar)
  if err != nil {
    fmt.Println("bad avatar:", err)
    return
  }
  fmt.Println("avatar is", len(img), "bytes")
}

如果你的 API 同时接受标准和 URL 安全字符串，务实的模式是先试一个解码器，如果它在末尾附近以 CorruptInputError 失败，就再试另一个，然后再放弃。这支舞别跳超过一次，也永远不要把"剥掉等号，然后祈祷"当作通用策略。

对 HTTP Basic 认证，你根本不用解码任何东西，因为 Go 替你做了。Request.BasicAuth，Go 1.4 起可用，替你拆分 Authorization 头并返回用户名和密码，而且已经对 RFC 2617 定义的 user:pass 对跑过了标准 base64 解码器：

package main

import (
  "fmt"
  "net/http"
)

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {
    user, pass, ok := r.BasicAuth()
    if !ok || user != "alice" || pass != "s3cret" {
      w.Header().Set("WWW-Authenticate", `Basic realm="api"`)
      w.WriteHeader(http.StatusUnauthorized)
      return
    }
    fmt.Fprintln(w, "hello", user)
  })
  http.ListenAndServe(":8080", mux)
}

记住，Basic 认证是认证，不是保护：这个头是 base64，不是加密，所以它只能走 HTTPS。如果你是客户机，镜像调用是 req.SetBasicAuth(user, pass)，它会用标准编码器替你构建同样的头。

API 处理程序的一个防御性习惯：解码之前先给正文设限，用 http.MaxBytesReader 或等价的长度检查。base64 字符串解码后大约是自己长度的四分之三，所以 N 字节的正文上限能把解码结果压在 N 字节以内，无论恶意客户端提交什么，内存都保持有界。解码无上限的正文是经典的内存耗尽向量，因为攻击者控制着能把多少兆字节的文本变成二进制。

遗留字符集

解码 base64 给你的是字节，在现代系统里，这些字节几乎总是 UTF-8，这种情况下 string(decoded) 就是全部故事。但 base64 是个老格式，其中很多是由使用 Windows-1252、ISO-8859-1、Shift JIS 或其他单字节、双字节遗留字符集的系统产生的。如果生产者那边用的是这些字符集，你解码出的字节就不是合法的 UTF-8，而 Go 不会假装它们是：它会在任何序列断裂的地方给你看替换字符。

Go 的答案是 golang.org/x/text 模块，它为常见字符集把遗留编码的字节转成 UTF-8（也能再转回去）。转换的位置就在解码之后，只需要一个函数调用：

package main

import (
  "encoding/base64"
  "fmt"

  "golang.org/x/text/encoding/charmap"
  "golang.org/x/text/transform"
)

func main() {
  // 遗留工具按 Windows-1252 存储的 "Café"，
  // 然后为传输做了 base64 编码
  encoded := "Q2Fm6Q=="
  raw, err := base64.StdEncoding.DecodeString(encoded)
  if err != nil {
    fmt.Println("decode failed:", err)
    return
  }
  utf8, _, err := transform.Bytes(charmap.Windows1252.NewDecoder(), raw)
  if err != nil {
    fmt.Println("charset conversion failed:", err)
    return
  }
  fmt.Println(string(utf8)) // Café
}

这个模块每个字符集家族有一个子包：charmap 处理 Windows 和 ISO 单字节表，japanese 处理 Shift JIS 和 EUC-JP，korean 处理 EUC-KR，simplifiedchinese 处理 GB18030，traditionalchinese 处理 Big5。经验法则：只有在你确实知道生产者的字符集时才转换，因为把 UTF-8 字节再转一次不会响亮地失败，它只会把文本弄乱。拿不准时，把载荷当作字节，让下游消费者去决定。

流式与分块解码

你在文件那一节见过 NewDecoder；下面是它值得单独占一节的原因。它是一个真正的流式适配器：只从底层读取器拉取需要的量，就地解码，并在流一坏掉的时候就返回 CorruptInputError。整个流可以是 TB 级；你握在内存里的只是你的缓冲区和你写出的输出。两种常见的消费模式：io.ReadAll 用于小流，io.Copy 用于其他一切：

small, err := io.ReadAll(base64.NewDecoder(base64.StdEncoding, r))
// 配置数据块或小型附件，用它没问题

w, err := io.Copy(out, base64.NewDecoder(base64.StdEncoding, r))
// 视频、tar 归档或恢复任务，用它没问题

Go 1.22 起，这个包还有 AppendDecode，它解码进一个你复用的缓冲区，而不是每次调用都分配一个新切片。它是那些在循环里解码大量块的热路径的工具，比如行处理器或协议解码器：

var buf []byte
for _, chunk := range chunks {
  buf, err = base64.StdEncoding.AppendDecode(buf, chunk)
  if err != nil {
    return err
  }
  process(buf)
}

这个方法把解码出的块追加到 buf 已有的内容之后，返回扩展后的切片，并按需扩展底层数组。在稳态下，也就是缓冲区已经长到合适尺寸时，它每个块零分配，这在基准测试里看得清清楚楚。如果你的负载是"偶尔解码一次"，DecodeString 是更简单的选择；如果是"在紧循环里解码成千上万次"，就该伸手拿 AppendDecode。

保持安全

几条安全提醒，专门针对 Go 程序实际使用这个包的方式。第一，base64 是编码，不是加密。一个 base64 字符串对任何拥有浏览器开发者工具的人都是可读的，所以"我们发送前先 base64 一下密码"不是安全措施，它是传输便利。机密性必须来自 TLS，而不是来自字母表。

第二，给你的输入设限。base64 字符串解码后的尺寸至多是其长度的 DecodedLen，所以分配之前先把这个数字和上限比一比，并在任何东西碰到解码器之前，给请求正文套一个尺寸上限。这两个检查各是一行代码，合在一起就把一次无界解码变成了有界解码。

第三，想清楚你打算怎么对待敷衍的输入。普通模式默默丢弃最后一组未使用的末尾比特，这意味着两个不同的字符串可以解码成相同的字节。对大多数数据来说无所谓。但对任何属于协议的一部分、一条签名消息、或者一个会被比较或存储的值，Strict() 是保守的选择，因为它让规范形式成为唯一被接受的形式。

第四，小心解码后的字节流向哪里。如果一个解码出的值变成了文件名、路径、SQL 片段或命令参数，base64 层并没有保护你免遭任何东西：这些字节现在是你程序不可信的输入，常规的净化规则完全像对待其他任何用户数据一样适用。

解码器有多快？

Go 里的 base64 很快，而且面对大数据仍然很快，因为实现是一个简单的查表循环，没有反射，没有每字符的分配。在一颗运行 Go 1.26 的现代桌面 CPU 上，一个 500 字节的字符串大约用四分之一微秒解码，一次分配，折算下来是每秒两 GB 的量级。一兆字节的 base64 解码远不到一毫秒；一吉字节远不到一秒。数字随硬件变动，但形状不变：base64 解码几乎从不是瓶颈；它周围的网络或磁盘才是。

如果你在热循环里，要盯着的是分配概况。DecodeString 每次调用都分配结果切片。Decode 配一个预置尺寸的目的地，AppendDecode 配一个复用的缓冲区，两者在稳态下都完全避免了那次分配。对每次请求发生几次的解码，这些都不重要；对每秒发生几百万次的解码，它决定你的内存曲线是平的，还是垃圾回收器在疯狂打转。

这个包的简史

base64 包是 Go 标准库里最老的部分之一。源文件的版权头写着 2009，语言诞生之年，而这个包从第一个稳定发行版 2012 年 3 月的 Go 1.0 起就是标准库的一部分。这意味着你今天调用的 DecodeString，就是 Go 程序十多年来一直调用的同一个 API，行为也相同。

此后的增长温和而有用。2015 年 8 月的 Go 1.5 加入了无填充的 RawStdEncoding 和 RawURLEncoding 值，为 JWT 风格的紧凑字符串打开了大门。2017 年 2 月的 Go 1.8 加入了 Strict()，让协议有了要求规范输入的手段。2024 年 2 月的 Go 1.22 把 AppendDecode 和 AppendEncode 加到了整个 base 编码家族，并收紧了 WithPadding 以拒绝胡闹的参数。截至 2026 年 9 月，最新发行版是 Go 1.27.1，另一条受支持的线是 Go 1.26，API 就是本文描述的那个：四个现成的编码、一个流解码器、一个严格模式，外加一个为性能准备的 append 家族。

更深一层的事实是兼容性承诺。Go 1 的保证意味着这个包会永远接受和拒绝相同的输入，所以今年你针对 2015 年产生的数据格式写的一个解码器，会一直工作下去。对一个这么老、这么无聊的格式来说，这就是最好的消息。

会让你惊讶的事

在 Go 里待过一段时间之后，base64 就不会再让你惊讶了，但头几次，下面这些事实会狠狠砸中你，所以都放在这里：

• 解码器跳过输入中任何位置的 \r 和 \n，但空格不跳，制表符不跳，零宽空格也不跳。这种宽容是刻意为之；它存在是为了让 MIME 折行输入能工作，而且它恰好停在规范停下的地方。
• 一次失败的解码仍然可能返回真实数据。部分结果是坏字节之前解码出的所有东西，错误是伴随它到来的，而不是取代它。
• CorruptInputError 字面意义上就是一个带了一个方法的 int64。"错误"就是偏移量，消息按需构建。
• Decode 和 Encode 都信任你能给它们的目的地缓冲区定好尺寸。给它们一个太小的缓冲区，你不会得到错误，你会得到 panic。
• 单个字符对四个内置编码中的任何一个都不是合法输入。一个 base64 字符携带 6 比特，一个字节需要 8 比特，所以一个字符里不存在完整的一组，无论带不带填充。
• 截至 2026 年 8 月，pkg.go.dev 上超过 244,000 个公开包把 encoding/base64 列在它们的导入里。它默默无闻地成为整个生态系统里被依赖最多的包之一。

解码在哪里出错

这些是不断在 Go 代码库里现身的解码错误，大致按它们在支持帖子里出现的顺序排列：

• 给 URL 安全数据选了 StdEncoding（或者反过来）。症状是在第一个 -、_、+ 或 / 处报错，修复方式是在挑解码器之前先看看字符串。
• 从终端、邮件或 PDF 粘贴字符串，混进了空格、制表符或行尾残留物。Go 跳过真正的换行，但字符串中间的一个空格就是损坏字节，错误里的偏移量会正正指着它。
• 忘了结果是 []byte。原样打印它得到一串数字，把它喂给期望字符串的函数则需要一次 string(...) 转换。
• 检查了错误，却还是用了部分数据。半解码的前缀是真实的，但它不是载荷，而把它当载荷的代码会在生产环境失败，数据恰好只有正确长度的一半。
• 用 len(src) 而不是 DecodedLen(len(src)) 给 Decode 缓冲区定尺寸。前一个尺寸错在你希望的反方向，而它触发的 panic 只在大输入上发生，这让它成为预发布环境的最爱。
• 假设 JWT 段带填充。它们不带，带填充的解码器会在最后一个字符处失败，错误读起来像一团谜。用 RawURLEncoding。
• 相信所有空白都会被跳过。不是的。只有两个换行字符会，而剪贴板里的"空白"是个大得多的家族。
• 当值是 base64 的 base64 时（一个被附加到一封邮件里的文件，而那封邮件本身又被附加了），解码了两次，或者忘了解码两次。检查只需一个来回：解码一次，看看结果是否还像 base64，然后再解码一次。

另一半工作

这就是故事里的整个解码侧：一个包，四个现成的解码器，一个大文件用的流解码器，一个挑剔协议用的严格模式，还有告诉你哪个字节出了错的错误消息。学会宽容规则，通过看字符来挑解码器，给你的输入设限，Go 里的 base64 就会变成它被设计成的样子：无聊、可预测、零依赖的工具。

当工作反过来，你的 Go 程序需要生产 base64 字符串而不是打开它们时，关于 Go 中 Base64 编码的相关文章会详细覆盖那一边：编码器单方法的 API、那个会默默吞掉你最后两个字节的 Close 调用、为 MIME 做的折行，以及四个编码如何映射到它们要穿行的通道上。

最后更新： 2026-09-08

相关文章： Go 中的 Base64 编码：完整指南