Image Base64 qui ne s'affiche pas ? 10 causes fréquentes et leurs solutions

Vous avez encodé une image en Base64, collé le data URI dans votre HTML, et… rien. Une icône d'image cassée vous fixe. Pire encore : ça fonctionne dans Chrome mais pas dans Safari, ou en local mais pas en production.

Les erreurs d'images Base64 sont frustrantes parce que la chaîne a l'air correcte au premier coup d'œil. La vraie cause se cache en général dans un détail subtil : un caractère manquant dans le préfixe, des espaces invisibles introduits par un copier-coller, ou un backend qui a silencieusement double-encodé vos données. Ce guide couvre les 10 causes les plus courantes avec des exemples de code et des correctifs.

Référence rapide : Symptôme → Cause → Solution

Commencez ici. Repérez votre symptôme, identifiez la cause probable et sautez directement à la solution détaillée plus bas.

Erreurs de préfixe : le data: URI est malformé

Le schéma data URI a une syntaxe stricte. Un seul caractère erroné et le navigateur traite votre chaîne Base64 comme une URL cassée au lieu de données image.

Cause 1 : Le préfixe data URI est totalement absent

Si vous affectez directement la chaîne Base64 brute à src sans le préfixe data:image/...;base64,, le navigateur l'interprète comme un chemin d'URL relatif — résultat : une 404.

❌ <img src="iVBORw0KGgo..." />
✅ <img src="data:image/png;base64,iVBORw0KGgo..." />

Cause 2 : Point-virgule écrit comme une virgule

Écrire data:image/png,base64,... au lieu de data:image/png;base64,... amène le navigateur à traiter base64,... comme du texte brut plutôt que comme un indicateur d'encodage Base64.

❌ data:image/png,base64,iVBORw0KGgo...
✅ data:image/png;base64,iVBORw0KGgo...

Cause 3 : Virgule manquante après "base64"

La virgule entre base64 et les données est obligatoire. Sans elle — data:image/png;base64iVBOR... — le navigateur lit base64iVBOR... comme un nom de charset, pas comme des données encodées.

❌ data:image/png;base64iVBORw0KGgo...
✅ data:image/png;base64,iVBORw0KGgo...

Corruption d'encodage : la chaîne Base64 elle-même est cassée

Même avec un préfixe correct, le contenu encodé peut être silencieusement corrompu lors du stockage, du transfert ou d'un copier-coller.

Cause 4 : Chaîne tronquée

Les colonnes de base de données avec une limite de caractères (par ex. VARCHAR(65535)) tronquent silencieusement les chaînes Base64. Un PNG de 100 Ko génère environ 136 000 caractères Base64. Si la colonne coupe à 65 535, vous obtenez une image à moitié décodée, corrompue. Solution : Utiliser des colonnes de type TEXT ou LONGTEXT pour stocker du Base64.

Cause 5 : Caractères illégaux (espaces, caractères spéciaux)

Un Base64 valide n'utilise que A-Z, a-z, 0-9, +, / et =. Les espaces introduits par un copier-coller font planter atob() avec InvalidCharacterError. Solution : Supprimer tous les espaces avant utilisation : str.replace(/\s/g, '').

Cause 6 : Pollution par les retours à la ligne

Des outils comme openssl base64 insèrent un \n tous les 76 caractères par défaut (RFC 2045). Ces sauts de ligne cassent les data URIs dans le HTML. Solution : Utiliser openssl base64 -A (sortie sur une seule ligne) ou supprimer les retours à la ligne : str.replace(/[\r\n]/g, '').

Cause 7 : Padding supprimé lors du passage en URL

Les caractères de padding (=) sont souvent supprimés lorsque la chaîne passe par des paramètres d'URL, car = est un caractère réservé. Certains navigateurs tolèrent l'absence de padding, d'autres non — d'où un comportement incohérent selon l'environnement. Solution : Encoder la chaîne Base64 en URL avant de la mettre dans un paramètre, ou re-padder côté réception.

Type MIME incorrect : est-ce que ça casse vraiment ?

Ça surprend beaucoup de développeurs : un type MIME erroné ne casse généralement pas l'affichage de l'image.

Cause 8 : Le MIME déclaré ne correspond pas au type réel du fichier

Si vous écrivez data:image/png;base64,/9j/4AAQ... (données JPEG avec un MIME PNG), la plupart des navigateurs modernes afficheront quand même l'image grâce au content sniffing. Mais ça peut échouer dans deux cas : (1) une Content Security Policy (CSP) stricte avec vérification MIME, et (2) un traitement côté serveur qui se fie au MIME déclaré pour la conversion de format. Verdict : À corriger par rigueur, mais c'est rarement la vraie cause d'un problème d'affichage.

Erreurs de pipeline : données corrompues avant d'arriver au navigateur

Ce sont les cas les plus difficiles à diagnostiquer car la chaîne Base64 semble correcte dans votre code — la corruption a lieu pendant la sérialisation ou la transmission.

Cause 9 : Double encodage Base64

Un backend qui encode des données déjà encodées produit le Base64 d'une chaîne Base64. Le résultat est ~33% plus long que prévu et, après un seul décodage, vous obtenez du texte au lieu de données binaires d'image. Comment détecter : Décodez une fois — si le résultat ressemble à une autre chaîne Base64 (commence par des lettres et se termine par =), vous avez un double encodage. Solution : Supprimer l'étape d'encodage superflue dans votre pipeline backend.

Cause 10 : Pollution par l'échappement JSON ou l'URL-encoding

Les chaînes Base64 contiennent des /. Certains sérialiseurs JSON les échappent en \/. Si le frontend lit le JSON brut sans le parser correctement (JSON.parse), les backslashes supplémentaires corrompent les données. De même, passer du Base64 dans des paramètres d'URL sans encodage transforme les + en espaces et supprime les = de padding. Solution : Toujours utiliser JSON.parse() pour les données JSON. Pour le transport par URL, utiliser encodeURIComponent().

Template de débogage systématique

Quand vous êtes bloqué, suivez cette procédure pas à pas pour isoler le problème :

1. Tester le data URI dans la barre d'adresse — Collez la chaîne complète data:image/...;base64,... directement dans la barre d'adresse du navigateur. Si l'image s'affiche, le problème vient de la façon dont votre application injecte la chaîne.
2. Vérifier la console du navigateur — Appuyez sur F12 et cherchez des erreurs comme net::ERR_INVALID_URL ou des violations CSP dans l'onglet Console.
3. Vérifier la longueur de la chaîne — Comparez la longueur de la chaîne Base64 à la source (backend) avec celle reçue côté frontend. Un écart signifie une troncature ou une corruption en transit.
4. Décoder et inspecter — Utilisez atob() dans la console pour décoder les premiers caractères. Si ça lève InvalidCharacterError, la chaîne contient des caractères illégaux.
5. Vérifier le double encodage — Décodez une fois. Si le résultat ressemble à une autre chaîne Base64, décodez à nouveau. Si le second décodage produit des données binaires, votre pipeline a une étape d'encodage en trop.

Validez votre Base64 instantanément avec ViewJSON

Au lieu d'inspecter manuellement les chaînes Base64, collez votre JSON dans ViewJSON. Il détecte automatiquement les médias encodés en Base64 par détection de magic numbers et affiche des aperçus intégrés — si l'aperçu s'affiche, votre Base64 est valide. Sinon, vous savez exactement quel champ est corrompu.