Изображение 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 символов; при обрезании на 65 535 байтах изображение повреждается при декодировании. Решение: выбрать тип, достаточный для вашей базы и кодировки, например MEDIUMTEXT или LONGTEXT в MySQL, и обнаруживать обрезание.

Причина 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- или form-параметрах; + также может превратиться в пробел. Решение: кодировать значение перед помещением в URL, при необходимости использовать URL-safe Base64 и проверять padding на принимающей стороне.

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

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

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

При data:image/png;base64,/9j/4AAQ... (JPEG объявлен как PNG) браузер может показать изображение, но результат зависит от обработки MIME конкретным потребителем. Строгий клиент или серверная конвертация могут завершиться ошибкой. Итог: согласуйте MIME с реальными байтами и рассматривайте расхождение как возможную, а не универсальную причину.

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

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

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

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

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

Base64 может повредиться, если сериализованный JSON или URL-данные обрабатываются как сырой текст. \/ безопасен после корректного JSON.parse(), но form-парсер может превратить + в пробел. Решение: парсить JSON, кодировать URL-значения и проверять декодированные байты на принимающей стороне.

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

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

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 валиден. Если нет — вы сразу видите, какое именно поле повреждено.