Руководство 3: добавить изображения в статьи и заметки

$ опубликовано 2026-11-13 | | обновлено 2026-11-14
Контекст: Как добавить изображения в Anglefeint, подготовить адаптивные варианты локально, сохранить их в Git и правильно развернуть сайт.

Оригиналы, обложки, постоянные адаптивные файлы и превью ссылок.


Вывод
слов 1.6k токенов 2.0k

Это руководство 3 из 8. Порядок всех руководств · Справочник настроек.

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

Ниже используются стандартные каталоги starter src/ и public/. Сначала определите назначение изображения:

Назначение Где указать Текущая обработка
Изображение текста статьи Markdown или MDX Исходный конвейер Markdown/MDX; не входит в постоянную подготовку обложек ниже
Обложка статьи heroImage в frontmatter Локальные адаптивные файлы, общие для списка и страницы статьи
Изображение заметки Markdown-изображение, ссылочное изображение или HTML img в тексте заметки Поддерживаемые локальные файлы используют те же постоянные адаптивные варианты для списка и превью главной
Превью ссылки ogImage статьи или site.ogImage Отдельная логика, не равнозначная миниатюре обложки

1. Добавьте оригинал в проект

Если изображение нужно одной статье, поместите его рядом с ней:

src/content/blog/zh/
  my-first-post.md
  photo.jpg
  cover.jpg

Для заметок также можно хранить изображение рядом с Markdown. Общие файлы нескольких страниц поместите в public/images/:

public/images/
  shared-photo.jpg
  fragments/
    my-photo.png

Несуществующие каталоги создайте самостоятельно. Для имён рекомендуются простые латинские буквы, цифры и дефисы, без неоднозначного регистра. В URL используйте /, а не пути компьютера C:\..., D:\... или обратные слеши. На регистрозависимой системе Photo.jpg и photo.jpg могут быть разными файлами.

Оригинал нужно сохранить. Созданные ниже WebP предназначены для показа и не заменяют резервную копию исходника.

2. Вставьте изображение в текст статьи

В нужном месте Markdown добавьте:

![Описание того, что на фотографии](./photo.jpg)

./photo.jpg относительно текущей статьи; в примере каталогов это файл рядом с ней. Для public используйте:

![Описание того, что на фотографии](/images/shared-photo.jpg)

Это public/images/shared-photo.jpg без public в адресе. В квадратных скобках — альтернативный текст: описывайте содержание, а не просто «картинка».

Обычные изображения текста можно увеличивать щелчком или Enter/пробелом после фокусировки; Esc, кнопка закрытия или фон закрывают просмотр. Обложки и изображения внутри ссылок/кнопок не участвуют. Используется уже выбранный браузером источник без автоматической загрузки оригинала повышенного качества и без переключения альбома.

Запуск prepare-covers не означает сжатие всех изображений текста. Он обрабатывает пул обложек, ссылки на обложки статей и локальные изображения заметок. Public-изображения обычного текста статьи по-прежнему могут загружаться оригиналом. Выбирайте подходящий объём, особенно избегайте прямой вставки скриншотов размером в несколько МБ.

3. Укажите обложку статьи

Положите cover.jpg рядом со статьёй, затем добавьте или измените в существующем frontmatter:

heroImage: ./cover.jpg

heroImage необязателен; при использовании должен ссылаться на локальный файл проекта, а не HTTPS-адрес. Не используйте /images/cover.jpg как public-URL этого поля: его правила отличаются от изображений текста.

Для централизованного хранения обложек используйте src/assets/blog/covers/originals/. Если статья находится в src/content/blog/zh/my-first-post.md, а оригинал — в src/assets/blog/covers/originals/my-cover.jpg, укажите:

heroImage: ../../../assets/blog/covers/originals/my-cover.jpg

Обложка не вставляется в текст автоматически. Она используется в списках блога/тегов и области обложки статьи. Макет может обрезать видимую область, но созданные изображения сохраняют исходные пропорции и не выбирают фокус на человеке или другом объекте автоматически.

new-post выбирает случайную обложку только из src/assets/blog/default-covers/. Изображение в covers/originals/ не выбирается автоматически: явно укажите его в статье.

4. Добавьте изображение в заметку

При theme.fragments.enabled: false dev, build и prepare-covers/doctor пропускают ссылки на изображения в тексте Fragments. Для изображений, включённых в обработку только этими ссылками, оригиналы и производные файлы больше не требуются. Ссылки на обложки и пулы src/assets/blog/default-covers/, src/assets/blog/covers/originals/ по-прежнему обрабатываются и проверяются, даже если изображение используется только в Fragments. Файлы не удаляются; повторное включение возобновляет обработку Fragments.

Примечание о версии: Изоляция изображений при отключении доступна с 0.36.1 и отсутствует в 0.36.0. Не считайте её доступной в старых версиях.

Поместите оригинал в public/images/fragments/my-photo.png и напишите в тексте существующей заметки:

![Описание изображения к заметке](/images/fragments/my-photo.png)

Можно также положить photo.png рядом с заметкой и использовать ![Описание изображения](./photo.png). Само добавление файла в public не запускает сканирование универсальной медиатеки: нужна ссылка из настоящей заметки.

Ссылочный синтаксис тоже поддерживается:

![Описание изображения][photo]

[photo]: /images/fragments/my-photo.png

Для ручных размеров используйте HTML:

<img src="/images/fragments/my-photo.png" alt="Описание изображения" width="640" height="360" />

Ширина и высота здесь примерные: укажите настоящие пропорции своего изображения. Для поддерживаемых локальных изображений отсутствующие размеры дополняются; существующие сохраняются, при одной стороне другая вычисляется по исходному соотношению. Ошибочные уже заданные размеры автоматически не исправляются.

Первое изображение каждой страницы списка заметок по умолчанию загружается приоритетно, остальные и миниатюры главной — лениво. Главная показывает ограниченное по высоте превью с обрезкой; это не полный просмотрщик. Щелчок по карточке ведёт к оригинальной заметке. Создание, постоянные ID и комментарии см. в руководстве по заметкам.

5. Подготовьте адаптивные файлы локально

После первой ссылки или замены оригинала запустите dev в корне проекта:

npm run dev

Dev, build и doctor, включая CI, повторно используют корректные производные и создают отсутствующие, устаревшие или повреждённые. Dev также отслеживает изменения источников и ссылок. Если нужны только изображения, остановите dev и выполните:

npx @anglefeint/astro-theme prepare-covers

Для проверки существующих файлов без создания:

npx @anglefeint/astro-theme prepare-covers --check

Заново кодировать всё каждый раз не нужно. Подготовка сравнивает хэши оригинала, правил обработки и результата для повторного использования. Изменение оригинала обновляет его варианты; отсутствие или изменение одного результата исправляет только необходимую часть. Не редактируйте манифест, не переименовывайте созданные файлы и не записывайте их URL обратно в статьи.

Текущие правила:

  • Статические растровые изображения преобразуются в WebP с качеством 80. Это сжатие с потерями, сохранность каждого пикселя не гарантируется.
  • Возможные ширины — 400, 640, 800, 960 и 1200px. Выбираются подходящие по ширине оригинала; при необходимости добавляется исходная ширина до 1200px. Маленькие изображения не увеличиваются.
  • Ориентация исправляется по EXIF, пропорции сохраняются. Варианты с другими композиционными кадрированиями не создаются.
  • SVG и многокадровая анимация сохраняют формат, не становятся статическим WebP. Однокадровый GIF может обрабатываться как статическое изображение; одного расширения недостаточно для решения.
  • Область обработки задают стандартный пул обложек, originals и фактические ссылки. Не все изображения public преобразуются подряд.

Браузер выбирает вариант по srcset, sizes, экрану и плотности пикселей. Поддерживать папки для разных размеров не нужно. Максимальный вариант — 1200px, поэтому детализация оригинала на больших экранах высокой плотности не гарантируется.

6. Что сохранять и что происходит при размещении?

После подготовки файлы расположены так:

src/assets/blog/covers/
  originals/      # если используется этот каталог оригиналов
  manifest.json  # источники, размеры, правила и хеши результатов
  generated/     # постоянные адаптивные файлы

Сохраните в Git вместе:

  1. Markdown статьи или заметки и новые/заменённые оригиналы.
  2. Весь src/assets/blog/covers/, включая манифест и созданные файлы.

Оригиналы из public или каталога статьи тоже сохраняйте: одних originals недостаточно. Несмотря на имя blog/covers, производные изображения заметок находятся здесь же.

Перед публикацией остановите dev и выполните локальный npm run doctor; после успеха можно открыть npm run preview. doctor уже включает сборку, повторять build сразу не нужно. На хостинге по-прежнему используйте npm run build и выходной каталог dist, размещая все его файлы.

Dev, build и doctor, включая CI, подготавливают используемые локальные изображения: корректные производные используются повторно, отсутствующие, устаревшие или повреждённые создаются заново. Сохраняйте оригиналы; добавление src/assets/blog/covers/, включая manifest.json и generated/, в Git позволяет повторно использовать результаты без зависимости от кэша хостинга. Отсутствующие или недопустимые оригиналы по-прежнему вызывают ошибку.

Требуется 0.36.2 или новее: Dev, build и doctor (включая CI) повторно используют корректные производные изображения и создают отсутствующие, устаревшие или повреждённые. В версии 0.36.1 перед build/CI сначала подготовьте изображения через dev или prepare-covers. Явная команда prepare-covers --check и синхронизация конфигурации остаются проверками без записи.

Используемые производные копируются в _blog-covers/ результата сборки. Не загружайте только HTML и не пропускайте этот каталог. Старые неиспользуемые generated не удаляются автоматически. Перед очисткой проверьте ссылки, не удаляйте нужные оригиналы.

Различия полей см. в heroImage/ogImage статьи и правилах превью заметок.

7. Какое изображение видно при публикации ссылки?

Превью ссылки — изображение карточки ссылки, а не обязательно обложка страницы.

По умолчанию при сборке для статьи создаётся PNG 1200×630 с заголовком, автором и названием сайта, без внешнего сервиса или браузерной генерации. После изменения данных пересоберите и разверните. theme.footer.showCredits также управляет подписью темы в автоматическом превью, не меняя загруженные вами изображения.

Укажите превью для одной статьи

Положите share.png рядом со статьёй и задайте в frontmatter:

ogImage: ./share.png

Либо поместите файл в public/images/share.png и укажите ogImage: /images/share.png. Поле поддерживает и прямые HTTPS-ссылки. Относительное локальное изображение проходит schema изображений статьи, public-путь проверяется на существование; доступность внешней ссылки зависит от стороннего сервера.

Задайте стандартное изображение страниц без собственного

Объедините со существующим верхнеуровневым site в src/site.config.ts:

site: {
  ogImage: '/images/site-share.jpg',
},

Сначала положите файл в public/images/site-share.jpg. site.ogImage поддерживает и HTTPS; отсутствие или пустое значение использует встроенное изображение 1200×630. Относительный путь статьи здесь недопустим.

Текущий приоритет:

  1. Явный ogImage статьи.
  2. Автоматическое превью статьи, если генерация включена.
  3. heroImage статьи после отключения theme.socialImage.enabled.
  4. site.ogImage страницы без собственного изображения, затем встроенное изображение темы.

Поэтому изменение только site.ogImage не заменяет автоматические изображения статей. Страница Fragments и ссылки #ID отдельных заметок используют общее стандартное изображение сайта, а не отдельные карточки.

Автоматические изображения находятся в dist/_social/. Платформы читают метаданные опубликованной страницы и могут кэшировать старое изображение; новый локальный результат не означает мгновенного обновления превью у них.

8. Если изображение отображается неверно

Симптом Что проверить сначала
Изображения нет Существование файла, регистр, относительный путь от текущего Markdown; public-URL без public
Не удалось подготовить обложку Локальный ли heroImage в проекте, не указан ли внешний/public URL; полная ошибка в терминале
missing/stale/modified derivatives Запустите dev, build или doctor для восстановления; prepare-covers запускает явную подготовку. Если ошибка остаётся, проверьте оригиналы
Файл в public не получил варианты Есть ли ссылка в тексте заметки; public-изображения обычной статьи не входят в это сканирование
GIF/SVG остаётся большим Анимация/вектор сохраняют исходный файл; команда не превращает их в видео и не сжимает анимацию
Внешнее изображение заметки медленное или сдвигает макет Внешние ссылки не преобразуются локально, удалённые размеры автоматически не определяются; оптимизируйте оригинал и укажите правильные размеры
Локально есть, после публикации нет Сохранены ли оригиналы, развёрнут ли весь dist, не переписаны ли пути; производные могут быть созданы при сборке
Старое превью ссылки Выполнены ли сборка/размещение, не имеет ли собственное изображение статьи приоритет над стандартным, нет ли кэша платформы

При нестандартных Astro srcDir, publicDir или исходных путях с base подготавливайте через dev проекта с его конфигурацией. Отдельный prepare-covers использует стандартные каталоги. Частичная поддержка base в обработке изображений не означает поддержку произвольного вложенного размещения всей темой.

Для установки и обновления см. первое руководство, для полей и текста статьи — второе.

Навигация по руководствам и настройкам

Назад: написать первую статью · Далее: опубликовать заметку · Все восемь руководств.

Связанные настройки: обложки и превью статей, изображения заметок, стандартное превью сайта. Полные пути, значения по умолчанию и ограничения — в общем справочнике.