Руководство 3: добавить изображения в статьи и заметки
Оригиналы, обложки, постоянные адаптивные файлы и превью ссылок.
На этой странице
Это руководство 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 относительно текущей статьи; в примере каталогов это файл рядом с ней. Для public используйте:

Это 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 и напишите в тексте существующей заметки:

Можно также положить 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 вместе:
- Markdown статьи или заметки и новые/заменённые оригиналы.
- Весь
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. Относительный путь статьи здесь недопустим.
Текущий приоритет:
- Явный
ogImageстатьи. - Автоматическое превью статьи, если генерация включена.
heroImageстатьи после отключенияtheme.socialImage.enabled.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 в обработке изображений не означает поддержку произвольного вложенного размещения всей темой.
Для установки и обновления см. первое руководство, для полей и текста статьи — второе.
Навигация по руководствам и настройкам
Назад: написать первую статью · Далее: опубликовать заметку · Все восемь руководств.
Связанные настройки: обложки и превью статей, изображения заметок, стандартное превью сайта. Полные пути, значения по умолчанию и ограничения — в общем справочнике.