﻿---
title: "Руководство 3: добавить изображения в статьи и заметки"
description: "Как добавить изображения в Anglefeint, подготовить адаптивные варианты локально, сохранить их в Git и правильно развернуть сайт."
url: "https://demo.anglefeint.com/ru/blog/starter-guide-images/"
language: "ru"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

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

Это руководство 3 из 8. [Порядок всех руководств](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/#tutorial-order) · [Справочник настроек](https://demo.anglefeint.com/ru/blog/config-reference/).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```yaml
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`, укажите:

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

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

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

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

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

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

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

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

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

Первое изображение каждой страницы списка заметок по умолчанию загружается приоритетно, остальные и миниатюры главной — лениво. Главная показывает ограниченное по высоте превью с обрезкой; это не полный просмотрщик. Щелчок по карточке ведёт к оригинальной заметке. Создание, постоянные ID и комментарии см. в [руководстве по заметкам](https://demo.anglefeint.com/ru/blog/starter-guide-5-fragments/).

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

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

```bash
npm run dev
```

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

```bash
npx @anglefeint/astro-theme prepare-covers
```

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

```bash
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\. Что сохранять и что происходит при размещении?

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

```text
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 статьи](https://demo.anglefeint.com/ru/blog/config-article/#frontmatter) и [правилах превью заметок](https://demo.anglefeint.com/ru/blog/config-fragments/#preview-and-links).

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

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

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

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

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

```yaml
ogImage: ./share.png
```

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

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

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

```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 в обработке изображений не означает поддержку произвольного вложенного размещения всей темой.

Для установки и обновления см. [первое руководство](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/), для полей и текста статьи — [второе](https://demo.anglefeint.com/ru/blog/starter-guide-2-languages-and-routing/).

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

[Назад: написать первую статью](https://demo.anglefeint.com/ru/blog/starter-guide-2-languages-and-routing/) · [Далее: опубликовать заметку](https://demo.anglefeint.com/ru/blog/starter-guide-5-fragments/) · [Все восемь руководств](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/#tutorial-order).

Связанные настройки: [обложки и превью статей](https://demo.anglefeint.com/ru/blog/config-article/), [изображения заметок](https://demo.anglefeint.com/ru/blog/config-fragments/), [стандартное превью сайта](https://demo.anglefeint.com/ru/blog/config-site-chrome/). Полные пути, значения по умолчанию и ограничения — в [общем справочнике](https://demo.anglefeint.com/ru/blog/config-reference/).
