Изображение Base64 не отображается? 10 частых причин и способы исправления

Вы закодировали изображение в Base64, вставили data URI в HTML и… ничего. Вместо картинки — иконка сломанного изображения. А бывает и хуже: в Chrome работает, в Safari — нет; локально всё отлично, а на продакшене — поломка.

Ошибки с Base64-изображениями особенно раздражают, потому что строка выглядит правильной на первый взгляд. Настоящая причина обычно прячется в мелочи: пропущенный символ в префиксе, невидимые пробелы после копипаста или бэкенд, который молча закодировал данные дважды. В этом руководстве разобраны все 10 типичных причин с примерами кода и конкретными решениями.

Краткая справка: Симптом → Причина → Решение

Начните отсюда. Найдите свой симптом, определите вероятную причину и переходите к подробному решению ниже.

Ошибки префикса: data: URI сформирован неправильно

Схема data URI имеет строгий синтаксис. Один неверный символ — и браузер воспринимает вашу Base64-строку как битую ссылку, а не как данные изображения.

Причина 1: Полностью отсутствует префикс data URI

Если вы подставляете «сырую» Base64-строку прямо в src без префикса data:image/...;base64,, браузер интерпретирует её как относительный URL — и выдаёт 404.

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

Причина 2: Точка с запятой написана как запятая

Если написать data:image/png,base64,... вместо data:image/png;base64,..., браузер воспримет base64,... как обычный текст, а не как индикатор Base64-кодирования.

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

Причина 3: Пропущена запятая после "base64"

Запятая между base64 и данными обязательна. Без неё — data:image/png;base64iVBOR... — браузер читает base64iVBOR... как имя charset, а не как закодированные данные.

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

Повреждение кодировки: сама Base64-строка сломана

Даже при правильном префиксе закодированные данные могут быть незаметно повреждены при сохранении, передаче или копипасте.

Причина 4: Строка обрезана

Колонки базы данных с ограничением длины (например, VARCHAR(65535)) молча обрезают Base64-строки. PNG размером 100 КБ генерирует ~136 000 символов Base64. Если колонка обрезает на 65 535, изображение декодируется лишь частично и оказывается битым. Решение: Использовать тип колонки TEXT или LONGTEXT для хранения Base64.

Причина 5: Недопустимые символы (пробелы, спецсимволы)

Валидный Base64 использует только A-Z, a-z, 0-9, +, / и =. Пробелы, попавшие при копировании, приводят к тому, что atob() выбрасывает InvalidCharacterError. Решение: Удалить все пробельные символы перед использованием: str.replace(/\s/g, '').

Причина 6: Загрязнение переносами строк

Инструменты вроде openssl base64 по умолчанию вставляют \n каждые 76 символов (RFC 2045). Эти переносы ломают data URI в HTML. Решение: Использовать openssl base64 -A (вывод в одну строку) или удалить переносы: str.replace(/[\r\n]/g, '').

Причина 7: Padding удалён при разборе URL

Символы padding (=) часто теряются при передаче через параметры URL, так как = — зарезервированный символ. Одни браузеры нормально обрабатывают отсутствующий padding, другие — нет, что приводит к непредсказуемому поведению. Решение: URL-кодировать Base64-строку перед помещением в параметр или восстанавливать padding на принимающей стороне.

Неверный MIME-тип: это действительно ломает отображение?

Это удивляет многих разработчиков: неправильно указанный MIME-тип обычно не мешает отображению изображения.

Причина 8: Указанный MIME не совпадает с реальным типом файла

Если вы пишете data:image/png;base64,/9j/4AAQ... (JPEG-данные с MIME-типом PNG), большинство современных браузеров всё равно отрендерят картинку благодаря content sniffing. Но это может не сработать в двух случаях: (1) строгая Content Security Policy (CSP) с проверкой MIME, и (2) серверная обработка, доверяющая объявленному MIME для конвертации формата. Итог: Стоит исправить ради корректности, но это крайне редко является реальной причиной проблемы.

Ошибки пайплайна: данные повреждены ещё до браузера

Это самые сложные для диагностики случаи — Base64-строка выглядит корректно в вашем коде, а повреждение происходит при сериализации или передаче.

Причина 9: Двойное Base64-кодирование

Бэкенд, который кодирует уже закодированные данные, создаёт Base64 от Base64-строки. Результат ~33% длиннее ожидаемого, а при однократном декодировании вы получаете текст вместо бинарных данных изображения. Как обнаружить: Декодируйте один раз — если результат похож на ещё одну Base64-строку (начинается с букв и заканчивается на =), значит, произошло двойное кодирование. Решение: Убрать лишний этап кодирования в пайплайне бэкенда.

Причина 10: Загрязнение JSON-экранированием или URL-кодированием

Base64-строки содержат /. Некоторые JSON-сериализаторы экранируют их как \/. Если фронтенд читает «сырой» JSON без корректного парсинга (JSON.parse), лишние обратные слеши портят данные. Аналогично, передача Base64 через URL-параметры без кодирования превращает + в пробелы и удаляет = padding. Решение: Всегда использовать JSON.parse() для JSON-данных. Для передачи через URL — encodeURIComponent().

Шаблон систематической отладки

Если вы зашли в тупик, пройдите по этим шагам, чтобы изолировать проблему:

1. Проверить data URI в адресной строке — Вставьте полную строку data:image/...;base64,... прямо в адресную строку браузера. Если изображение отобразилось — проблема в том, как ваше приложение подставляет строку.
2. Проверить консоль браузера — Нажмите F12 и поищите ошибки вроде net::ERR_INVALID_URL или нарушения CSP во вкладке Console.
3. Сравнить длину строки — Сравните длину Base64-строки на стороне бэкенда с тем, что приходит на фронтенд. Расхождение означает обрезку или повреждение при передаче.
4. Декодировать и осмотреть — Используйте atob() в консоли, чтобы декодировать первые символы. Если выбрасывает InvalidCharacterError — в строке есть недопустимые символы.
5. Проверить двойное кодирование — Декодируйте один раз. Если результат выглядит как ещё одна Base64-строка, декодируйте повторно. Если второй decode выдаёт бинарные данные — в вашем пайплайне лишний этап кодирования.

Мгновенная проверка Base64 с помощью ViewJSON

Вместо ручного разбора Base64-строк вставьте JSON в ViewJSON. Он автоматически определяет Base64-медиа через детекцию magic numbers и показывает встроенные превью — если превью появилось, ваш Base64 валиден. Если нет — вы сразу видите, какое именно поле повреждено.