Décoder Base64 en Go — Guide encoding/base64 + Exemples

Le décodage Base64 en Go est omniprésent — inspection de JWT, pièces jointes binaires, payloads d'API de services cloud. Le package standard encoding/base64de Go couvre tous ces cas, mais choisir la mauvaise variante d'encodage (standard vs URL-safe, avec ou sans padding) est la principale source d'erreurs “illegal base64 data”. Ce guide couvre StdEncoding, URLEncoding, RawURLEncoding, le décodage en streaming avec base64.NewDecoder, l'inspection de payloads JWT, et quatre erreurs classiques qui piègent presque tout le monde la première fois. Pour un décodage ponctuel dans le navigateur, le Décodeur Base64 de ToolDeck fait le travail instantanément sans écrire une seule ligne de code.

Qu'est-ce que le décodage Base64 ?

L'encodage Base64 représente des données binaires sous forme de texte ASCII en utilisant 64 caractères imprimables (A–Z, a–z, 0–9, plus deux caractères supplémentaires). Le décodage effectue l'opération inverse — il convertit cette représentation ASCII en les octets d'origine. Chaque groupe de 4 caractères Base64 se décode en exactement 3 octets. Ce schéma existe parce que de nombreuses couches de transport (email, en-têtes HTTP, champs JSON) sont conçues pour le texte, pas pour le binaire brut. Voici à quoi ressemble un aller-retour complet :

package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	// Octets bruts → encodés en Base64 → décodés en octets bruts
	original := []byte("service_token:xK9mP2qR")
	// Encodé : "c2VydmljZV90b2tlbjp4SzltUDJxUg=="

	encoded := base64.StdEncoding.EncodeToString(original)
	decoded, _ := base64.StdEncoding.DecodeString(encoded)
	fmt.Println(string(decoded) == string(original)) // true
}

Décoder du Base64 en Go avec encoding/base64

Le package encoding/base64est livré avec Go — aucune dépendance externe. Il expose quatre variantes d'encodage prédéfinies sous forme de variables au niveau du package. La fonction la plus couramment utilisée pour une entrée de type string est DecodeString, qui retourne un slice d'octets et une erreur.

package main

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

func main() {
	// Base64 standard — l'alphabet utilise + et / avec le padding =
	encoded := "eyJob3N0IjoiZGItcHJvZC51cy1lYXN0LTEiLCJwb3J0Ijo1NDMyfQ=="
	decoded, err := base64.StdEncoding.DecodeString(encoded)
	if err != nil {
		log.Fatalf("decode error: %v", err)
	}
	fmt.Println(string(decoded))
	// {"host":"db-prod.us-east-1","port":5432}
}

La méthode Decodeopère sur des slices d'octets plutôt que sur des strings, et écrit le résultat dans un buffer de destination pré-alloué. Il faut dimensionner le buffer correctement — utilisez base64.StdEncoding.DecodedLen(len(src)) pour obtenir la taille maximale (elle peut être légèrement supérieure à la longueur réelle décodée en raison du padding).

package main

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

func main() {
	src := []byte("eyJob3N0IjoiZGItcHJvZCIsInBvcnQiOjU0MzJ9")
	dst := make([]byte, base64.RawStdEncoding.DecodedLen(len(src)))

	n, err := base64.RawStdEncoding.Decode(dst, src)
	if err != nil {
		log.Fatalf("decode: %v", err)
	}
	fmt.Println(string(dst[:n]))
	// {"host":"db-prod","port":5432}
}

StdEncoding vs URLEncoding — Choisir la bonne variante

C'est là que réside la confusion principale. Le package encoding/base64de Go expose quatre objets d'encodage, et choisir le mauvais provoque systématiquement une erreur. La différence repose sur deux éléments : l'alphabet et le padding.

package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	// Payload d'en-tête JWT — URL-safe, sans padding
	jwtHeader := "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjMtMDkifQ"

	// Incorrect : StdEncoding échoue sur une entrée URL-safe sans padding
	_, err1 := base64.StdEncoding.DecodeString(jwtHeader)
	fmt.Println("StdEncoding error:", err1)
	// StdEncoding error: illegal base64 data at input byte 43

	// Correct : RawURLEncoding — sans padding, alphabet URL-safe
	decoded, err2 := base64.RawURLEncoding.DecodeString(jwtHeader)
	fmt.Println("RawURLEncoding ok:", err2, "→", string(decoded))
	// RawURLEncoding ok: <nil> → {"alg":"RS256","kid":"2023-09"}
}

Les quatre variantes en termes simples :

Ma règle empirique : si la donnée provient d'un JWT, d'un flux OAuth ou d'un SDK cloud, commencez par RawURLEncoding. Si elle provient de pièces jointes email ou d'anciens formulaires web, essayez StdEncoding. Le message d'erreur indique toujours la position exacte de l'octet où le décodage a échoué.

Décoder du Base64 depuis un fichier et une réponse d'API

Lire un fichier encodé en Base64

Les fichiers binaires (images, PDF, certificats) sont parfois stockés encodés en Base64 sur disque. Lisez le fichier, supprimez les espaces en fin de chaîne, puis décodez :

package main

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

func main() {
	raw, err := os.ReadFile("certificate.pem.b64")
	if err != nil {
		log.Fatalf("read file: %v", err)
	}

	// Supprime les sauts de ligne — les fichiers Base64 ont souvent des retours ligne toutes les 76 colonnes
	cleaned := strings.ReplaceAll(strings.TrimSpace(string(raw)), "\n", "")

	decoded, err := base64.StdEncoding.DecodeString(cleaned)
	if err != nil {
		log.Fatalf("decode: %v", err)
	}

	if err := os.WriteFile("certificate.pem", decoded, 0600); err != nil {
		log.Fatalf("write: %v", err)
	}
	fmt.Printf("decoded %d bytes → certificate.pem\n", len(decoded))
}

Décoder un champ Base64 depuis une réponse JSON d'API

Les API cloud retournent fréquemment des données binaires (clés de chiffrement, blobs signés, miniatures) sous forme de chaînes Base64 dans du JSON. Désérialisez d'abord le JSON, puis décodez le champ ciblé :

package main

import (
	"encoding/base64"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

type SecretResponse struct {
	Name    string `json:"name"`
	Payload string `json:"payload"` // Valeur secrète encodée en Base64
	Version int    `json:"version"`
}

func fetchAndDecodeSecret(secretURL string) ([]byte, error) {
	resp, err := http.Get(secretURL)
	if err != nil {
		return nil, fmt.Errorf("http get: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("unexpected status: %d", resp.StatusCode)
	}

	var secret SecretResponse
	if err := json.NewDecoder(resp.Body).Decode(&secret); err != nil {
		return nil, fmt.Errorf("decode json: %w", err)
	}

	value, err := base64.StdEncoding.DecodeString(secret.Payload)
	if err != nil {
		return nil, fmt.Errorf("decode base64: %w", err)
	}
	return value, nil
}

func main() {
	value, err := fetchAndDecodeSecret("https://api.example.com/secrets/db-password")
	if err != nil {
		log.Fatalf("fetch secret: %v", err)
	}
	fmt.Printf("secret value: %s\n", value)
}

Décodage en streaming de fichiers Base64 volumineux

Charger un fichier de 500 Mo encodé en Base64 en mémoire avec os.ReadFile puis appeler DecodeString consomme environ 750 Mo de RAM (la chaîne encodée plus les octets décodés). base64.NewDecoder encapsule n'importe quel io.Readeret décode par blocs, maintenant l'utilisation mémoire quasi-constante. Combinez-le avec io.Copy pour un pipeline de streaming propre :

package main

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

func streamDecodeFile(srcPath, dstPath string) error {
	src, err := os.Open(srcPath)
	if err != nil {
		return fmt.Errorf("open source: %w", err)
	}
	defer src.Close()

	dst, err := os.Create(dstPath)
	if err != nil {
		return fmt.Errorf("create dest: %w", err)
	}
	defer dst.Close()

	decoder := base64.NewDecoder(base64.StdEncoding, src)
	written, err := io.Copy(dst, decoder)
	if err != nil {
		return fmt.Errorf("stream decode: %w", err)
	}
	fmt.Printf("written %d bytes to %s\n", written, dstPath)
	return nil
}

func main() {
	if err := streamDecodeFile("backup.tar.b64", "backup.tar"); err != nil {
		log.Fatal(err)
	}
}

Décodage Base64 depuis la ligne de commande

La plupart des développeurs Go utilisent en premier la ligne de commande pour déboguer. Chaque système macOS et Linux embarque base64; sous Windows, PowerShell dispose d'un équivalent intégré. Pour inspecter rapidement des payloads d'API, c'est plus rapide qu'écrire un script Go.

# Décoder une chaîne Base64 (Linux / macOS)
echo "eyJob3N0IjoiZGItcHJvZCIsInBvcnQiOjU0MzJ9" | base64 --decode
# {"host":"db-prod","port":5432}

# Décoder et formatter avec jq (diriger la sortie JSON)
echo "eyJob3N0IjoiZGItcHJvZCIsInBvcnQiOjU0MzJ9" | base64 --decode | jq .
# {
#   "host": "db-prod",
#   "port": 5432
# }

# Décoder un fichier encodé en Base64 vers du binaire
base64 --decode < encrypted_payload.b64 > encrypted_payload.bin

# macOS utilise le flag -D au lieu de --decode
echo "c2VjcmV0LXRva2Vu" | base64 -D

Pour inspecter des tokens JWT sans aucun outil installé, collez le token dans le Décodeur Base64 de ToolDeck — divisez sur les points et décodez chaque partie.

Alternative haute performance : encoding/base64 est déjà rapide

Contrairement à Python où le débat orjson vs json a du sens en termes de performance, le package encoding/base64de Go est déjà optimisé en assembleur et genuinement rapide pour la plupart des charges de travail. Cela dit, si vous traitez des millions d'enregistrements dans une boucle serrée, filippo.io/base64 offre un décodage accéléré par SIMD avec une API identique.

go get filippo.io/base64

package main

import (
	"fmt"
	"log"

	"filippo.io/base64"
)

func main() {
	// Remplacement direct — même API que encoding/base64
	encoded := "eyJob3N0IjoiY2FjaGUtcHJvZCIsInBvcnQiOjYzNzl9"
	decoded, err := base64.StdEncoding.DecodeString(encoded)
	if err != nil {
		log.Fatalf("decode: %v", err)
	}
	fmt.Println(string(decoded))
	// {"host":"cache-prod","port":6379}
}

Le gain de performance est le plus visible sur amd64 avec support AVX2 — les benchmarks montrent une amélioration de 2 à 4× du débit sur des entrées volumineuses. Pour le décodage courant de réponses d'API (quelques centaines d'octets à la fois), restez avec la bibliothèque standard.

Décoder le payload JWT Base64 en Go

L'inspection de JWT revient dans presque chaque service backend. D'après mon expérience, la plupart des sessions de débogage se résument à “qu'y a-t-il vraiment dans ce token ?” — et vous pouvez répondre à cette question sans importer une bibliothèque JWT complète. Le token comporte trois segments encodés en Base64url séparés par des points. Le segment du milieu est le payload qui vous intéresse :

package main

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

type JWTPayload struct {
	Subject  string   `json:"sub"`
	Issuer   string   `json:"iss"`
	Expiry   int64    `json:"exp"`
	Roles    []string `json:"roles"`
}

func decodeJWTPayload(token string) (*JWTPayload, error) {
	parts := strings.Split(token, ".")
	if len(parts) != 3 {
		return nil, fmt.Errorf("invalid JWT: expected 3 segments, got %d", len(parts))
	}

	// JWT utilise RawURLEncoding — alphabet URL-safe, sans padding =
	raw, err := base64.RawURLEncoding.DecodeString(parts[1])
	if err != nil {
		return nil, fmt.Errorf("decode payload: %w", err)
	}

	var payload JWTPayload
	if err := json.Unmarshal(raw, &payload); err != nil {
		return nil, fmt.Errorf("unmarshal payload: %w", err)
	}
	return &payload, nil
}

func main() {
	token := "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c3ItNDQyIiwiaXNzIjoiYXV0aC5leGFtcGxlLmNvbSIsImV4cCI6MTc0MTk1NjgwMCwicm9sZXMiOlsiYWRtaW4iLCJhdWRpdG9yIl19.SIGNATURE"

	payload, err := decodeJWTPayload(token)
	if err != nil {
		log.Fatalf("jwt: %v", err)
	}
	fmt.Printf("Subject: %s\n", payload.Subject)
	fmt.Printf("Issuer:  %s\n", payload.Issuer)
	fmt.Printf("Roles:   %v\n", payload.Roles)
	// Subject: usr-442
	// Issuer:  auth.example.com
	// Roles:   [admin auditor]
}

Erreurs fréquentes

J'ai rencontré ces quatre erreurs dans de vraies revues de code — les deux premières apparaissent presque systématiquement quand quelqu'un intègre un nouveau fournisseur d'authentification.

// En-tête JWT — URL-safe, sans padding
token := "eyJhbGciOiJSUzI1NiJ9"
decoded, err := base64.StdEncoding.DecodeString(token)
// err: illegal base64 data at input byte 19

// En-tête JWT — encodage correct
token := "eyJhbGciOiJSUzI1NiJ9"
decoded, err := base64.RawURLEncoding.DecodeString(token)
// decoded: {"alg":"RS256"}
// err: nil

dst := make([]byte, base64.StdEncoding.DecodedLen(len(src)))
base64.StdEncoding.Decode(dst, src)
fmt.Println(string(dst)) // peut inclure des octets nuls en fin de buffer

dst := make([]byte, base64.StdEncoding.DecodedLen(len(src)))
n, err := base64.StdEncoding.Decode(dst, src)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(dst[:n])) // correct — uniquement les octets décodés

// Valeur lue dans un fichier de config avec un saut de ligne final
encoded := "c2VydmljZV9rZXk6eEtNcDI=\n"
decoded, err := base64.StdEncoding.DecodeString(encoded)
// err: illegal base64 data at input byte 24

encoded := "c2VydmljZV9rZXk6eEtNcDI=\n"
cleaned := strings.TrimSpace(encoded)
decoded, err := base64.StdEncoding.DecodeString(cleaned)
// decoded: "service_key:xKMp2"
// err: nil

decoded, _ := base64.StdEncoding.DecodeString(pngBase64)
// Traiter un PNG binaire comme une string perd des données
imageStr := string(decoded)
os.WriteFile("image.png", []byte(imageStr), 0644) // peut corrompre

decoded, err := base64.StdEncoding.DecodeString(pngBase64)
if err != nil {
    log.Fatal(err)
}
// Écrire les octets directement — sans conversion en string
os.WriteFile("image.png", decoded, 0644)

Comparaison des méthodes

Toutes les variantes font partie de la bibliothèque standard — aucune dépendance externe nécessaire.

Pour les tokens JWT et les flux OAuth : RawURLEncoding. Pour les pièces jointes email et les données MIME : StdEncoding. Pour les fichiers binaires volumineux depuis le disque ou le réseau : encapsulez un reader dans base64.NewDecoder— l'utilisation mémoire reste constante quelle que soit la taille du fichier. Besoin d'un alphabet personnalisé ? base64.NewEncoding(alphabet)construit un nouvel objet d'encodage pour les cas d'usage exotiques.

Pour des vérifications ponctuelles rapides en développement, le Décodeur Base64 en ligne est plus rapide que lancer un programme Go.

Questions fréquentes

package main

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

func main() {
	encoded := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
	decoded, err := base64.RawURLEncoding.DecodeString(encoded)
	if err != nil {
		log.Fatalf("decode: %v", err)
	}
	fmt.Println(string(decoded))
	// {"alg":"HS256","typ":"JWT"}
}

package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	// Standard : peut contenir les caractères + / et =
	std := base64.StdEncoding.EncodeToString([]byte("hello/world"))
	fmt.Println(std) // "aGVsbG8vd29ybGQ="

	// URL-safe : remplace + par - et / par _
	url := base64.URLEncoding.EncodeToString([]byte("hello/world"))
	fmt.Println(url) // "aGVsbG8vd29ybGQ=" (identique ici — la différence apparaît avec d'autres octets)

	// Les en-têtes JWT n'ont jamais de padding — utilisez RawURLEncoding
	raw := base64.RawURLEncoding.EncodeToString([]byte("hello/world"))
	fmt.Println(raw) // "aGVsbG8vd29ybGQ" (sans = final)
}

package main

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

func main() {
	// Entrée reçue d'un webhook — contient des sauts de ligne du format wire
	raw := "  aGVsbG8gd29ybGQ=  \n"
	cleaned := strings.TrimSpace(raw)

	decoded, err := base64.StdEncoding.DecodeString(cleaned)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(decoded)) // hello world
}

package main

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

func main() {
	src, err := os.Open("attachment.b64")
	if err != nil {
		log.Fatal(err)
	}
	defer src.Close()

	dst, err := os.Create("attachment.bin")
	if err != nil {
		log.Fatal(err)
	}
	defer dst.Close()

	decoder := base64.NewDecoder(base64.StdEncoding, src)
	io.Copy(dst, decoder)
}

package main

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

func main() {
	token := "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c3ItOTAxIiwicm9sZSI6ImFkbWluIn0.SIG"
	parts := strings.Split(token, ".")
	if len(parts) < 2 {
		log.Fatal("invalid JWT format")
	}

	payload, err := base64.RawURLEncoding.DecodeString(parts[1])
	if err != nil {
		log.Fatalf("decode payload: %v", err)
	}
	fmt.Println(string(payload))
	// {"sub":"usr-901","role":"admin"}
}

package main

import (
	"encoding/base64"
	"strings"
)

// Détecte la variante d'encodage à partir de la chaîne encodée
func decodeAPIPayload(encoded string) ([]byte, error) {
	// Caractères URL-safe sans padding — courant dans les API modernes
	if !strings.Contains(encoded, "+") && !strings.Contains(encoded, "/") {
		return base64.RawURLEncoding.DecodeString(encoded)
	}
	// Base64 standard avec padding
	return base64.StdEncoding.DecodeString(encoded)
}

Outils associés

• Encodeur Base64 — encodez des données binaires ou du texte en Base64 dans le navigateur, utile pour générer des fixtures de test à coller dans vos tests unitaires Go.
• Décodeur JWT — divisez et décodez les trois segments JWT en une seule fois, avec inspection champ par champ du payload — aucun code Go requis quand vous devez simplement lire un token lors du débogage.
• Décodeur URL — décodez les chaînes percent-encodées, pratique quand les réponses d'API mélangent des données Base64url avec des paramètres de requête percent-encodés.
• Formateur JSON — après avoir décodé un payload JWT Base64 ou une réponse d'API, collez le JSON ici pour formatter et valider la structure instantanément.