encoding/base64

Std, URL, and raw Base64 encodings, padding, and CorruptInputError, checked on Go 1.24.0.

模块页正文目前为英文。

The encoding/base64 package implements Base64 as specified by RFC 4648. Import it as "encoding/base64". Examples were checked on Go 1.24.0.

StdEncoding uses A-Za-z0-9+/ and writes = padding. URLEncoding uses A-Za-z0-9-_ instead of + and /, and still writes padding. RawStdEncoding and RawURLEncoding are the same alphabets with padding omitted, produced by WithPadding(NoPadding).

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
base64.StdEncoding.EncodeToString, base64.URLEncoding.EncodeToString, base64.RawStdEncoding, base64.RawURLEncodingEncode bytes with the standard or URL alphabet, with or without padding.
Encoding.DecodeString, base64.CorruptInputErrorDecode a Base64 string, and report malformed input as CorruptInputError without depending on the error text.

Std, URL, and raw encodings

EncodeToString maps three input bytes to four output characters. When the input length is not a multiple of three, StdEncoding and URLEncoding append one or two = padding characters. RawStdEncoding and RawURLEncoding omit that padding, so the same input "hello" is aGVsbG8= with padding and aGVsbG8 without it.

The URL alphabet replaces + with - and / with _. For the three bytes {0xfb, 0xef, 0xff}, StdEncoding produces ++// and URLEncoding produces --__. Those two strings are not interchangeable at decode time.

base64.StdEncoding.EncodeToString, base64.URLEncoding.EncodeToString, base64.RawStdEncoding, base64.RawURLEncoding

func (enc *Encoding) EncodeToString(src []byte) string
var StdEncoding = NewEncoding("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/")
var URLEncoding = NewEncoding("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_")
var RawStdEncoding = StdEncoding.WithPadding(NoPadding)
var RawURLEncoding = URLEncoding.WithPadding(NoPadding)
const StdPadding rune = '='
const NoPadding rune = -1

Encode bytes with the standard or URL alphabet, with or without padding.

ParameterDescription
srcThe bytes to encode. EncodeToString does not modify src.

Returns: The Base64 string. Std and URL encodings include = padding when needed. The raw encodings do not.

  • NewEncoder writes to an io.Writer and must be Closed to flush any remaining bytes and padding. This example uses EncodeToString only.
go
package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	src := []byte("hello")
	fmt.Println(base64.StdEncoding.EncodeToString(src))
	fmt.Println(base64.RawStdEncoding.EncodeToString(src))
	fmt.Println(base64.URLEncoding.EncodeToString(src))
	fmt.Println(base64.RawURLEncoding.EncodeToString(src))
	b := []byte{0xfb, 0xef, 0xff}
	fmt.Println(base64.StdEncoding.EncodeToString(b))
	fmt.Println(base64.URLEncoding.EncodeToString(b))
	fmt.Println(base64.RawStdEncoding.EncodeToString(b))
	fmt.Println(base64.RawURLEncoding.EncodeToString(b))
}

Expected output

aGVsbG8=
aGVsbG8
aGVsbG8=
aGVsbG8
++//
--__
++//
--__

Official documentation →

Decoding, padding, and CorruptInputError

DecodeString returns the decoded bytes. Official documentation says that if the input is malformed it returns the partially decoded data and a CorruptInputError, whose value is the index of the first unexpected byte. Newline characters are ignored.

StdEncoding requires padding when the length needs it: aGVsbG8 without = is an error, while RawStdEncoding accepts that string. Conversely, RawStdEncoding rejects a trailing =, because = is not in the alphabet. URLEncoding rejects a standard string that contains + or /.

Encoding.DecodeString, base64.CorruptInputError

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

Decode a Base64 string, and report malformed input as CorruptInputError without depending on the error text.

ParameterDescription
sThe Base64 string to decode. It must use the same alphabet and padding rules as enc.

Returns: The decoded bytes and a nil error, or partial data and a CorruptInputError.

Errors

  • CorruptInputError — The input does not match this encoding. The integer value is the byte index in s where decoding failed, measured here as 4 for missing Std padding, 7 for a raw decode of a padded string, and 0 for a URL decode of ++//.
  • The examples use errors.As and int64(err) rather than the error string, which is not an operating-system message but is still not the API contract you should switch on.
go
package main

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

func main() {
	dec, err := base64.StdEncoding.DecodeString("aGVsbG8=")
	fmt.Printf("%s %v\n", dec, err)
	var ce base64.CorruptInputError
	_, err = base64.StdEncoding.DecodeString("aGVsbG8")
	fmt.Println(errors.As(err, &ce), int64(ce))
	dec, err = base64.RawStdEncoding.DecodeString("aGVsbG8")
	fmt.Printf("%s %v\n", dec, err)
	_, err = base64.RawStdEncoding.DecodeString("aGVsbG8=")
	fmt.Println(errors.As(err, &ce), int64(ce))
	_, err = base64.URLEncoding.DecodeString("++//")
	fmt.Println(errors.As(err, &ce), int64(ce))
}

Expected output

hello <nil>
true 4
hello <nil>
true 7
true 0

Official documentation →