Генерация динамических изображений Open Graph на граничных узлах (Edge): CldOgImage, Next.js Metadata API и текстовые оверлеи Cloudinary

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

В рабочем проекте используется Cloudinary для обрезки исходного актива, его затемнения, добавления текстовых слоев, оптимизации доставки и возврата единого URL для шеринга. Студия на Vite делает трансформацию наглядной, а прилагаемый рецепт Next.js связывает ту же идею с метаданными страницы.

Коротко: сохраняйте каждое исходное изображение в Cloudinary, а затем храните его public_id вместе с данными вашей статьи. Сформируйте URL доставки Cloudinary из этого ID, названия статьи и настроек вашего бренда. В проекте на базе Next.js App Router возвращайте этот URL из generateMetadata. В проекте с Pages Router используйте CldOgImage.

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

• Откройте интерактивную Edge OG Studio.
• Просмотрите репозиторий на GitHub.
• Прочтите полную Next.js production recipe.

Студия на Vite генерирует URL-адреса Cloudinary и иллюстрирует превью для Facebook, X, LinkedIn и Slack. Рецепт Next.js выдает производственные метаданные.

Студия объединяет пять частей рабочего процесса создания социальных изображений:

• Библиотека активов Cloudinary и загрузка из браузера
• Трансформация 1200 x 630 с автоматическим определением фокуса (gravity)
• Динамические текстовые слои для серии, названия и автора
• Редактируемое поле альтернативного текста (alt), сохраняемое как контекст загрузки
• Превью ленты новостей, в которых используется тот же сгенерированный URL

Откройте полный редактор в StudioPage.tsx и карточки платформ в SocialPreviews.tsx.

Откройте полный редактор в и карточки платформ в .

Когда вы делитесь статьей в Facebook, X или LinkedIn, платформа не делает скриншот страницы. Она считывает метаданные Open Graph страницы. Одно поле, называемое og:image, сообщает платформе, какое изображение нужно показать вместе с заголовком и описанием статьи.

В этом проекте Next.js создает уникальное значение og:image для каждой статьи. Это значение представляет собой URL-адрес Cloudinary, созданный на основе главного изображения (hero image), заголовка и автора статьи. Когда социальная платформа запрашивает этот URL, Cloudinary обрезает главное изображение, накладывает поверх детали статьи и возвращает готовую социальную карточку размером 1200 x 630.

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

URL-адрес изображения Cloudinary — это адрес, который также содержит инструкции по трансформации. Он указывает Cloudinary, какой исходный актив использовать, как его обрезать и какой текст разместить поверх. Студия на Vite отображает этот же URL, чтобы вы могли предварительно просмотреть результат перед подключением рецепта к метаданным Next.js.

В этом руководстве термин «на граничных узлах (at the edge)» означает, что завершенная трансформация распространяется через глобальную инфраструктуру доставки Cloudinary. Это не означает, что пример запускается в средовом исполнении Next.js Edge Runtime.

Вам понадобятся:

• Node.js 22
• Аккаунт Cloudinary и рабочее окружение продукта
• Проект Next.js для интеграции производственных метаданных
• Базовые знания React и TypeScript
• Аккаунт Netlify только в том случае, если вы хотите воспроизвести развертывание демоверсии

Клонируйте и запустите:

Пресет загрузки сохраняет правила загрузки в Cloudinary. Браузер отправляет имя пресета, и Cloudinary применяет папку, правила именования, формат, размер и настройки безопасности пресета.

Откройте Консоль Cloudinary > Настройки (Settings) > Загрузка (Upload) > Пресеты загрузки (Upload Presets), затем выберите Добавить пресет загрузки (Add Upload Preset). Используйте следующие значения для этой сборки:

Cloudinary документирует эти элементы управления в своем руководстве по пресетам загрузки. Имена пресетов остаются видимыми в коде браузера, поэтому применяйте перечисленные ограничения.

Добавьте edge-og-studio и blog-hero в разделе Управление и анализ (Manage and Analyze) > Теги (Tags). Вы также можете добавить входящую трансформацию c_limit,w_2400,h_2400, чтобы уменьшить слишком большие оригиналы перед сохранением.

Не добавляйте f_auto во входящую трансформацию. Выбор автоматического формата зависит от запроса на доставку, поэтому он относится к URL-адресу доставки.

Используйте неподписанный пресет для контролируемой публичной демоверсии, где ограничения пресета определяют разрешенное поведение загрузки. Используйте подписанную загрузку для авторизованных авторов, частных рабочих процессов, папок для конкретных арендаторов (tenants) или одобренных сервером параметров.

Подписанная загрузка Next.js требует серверного маршрута, который считывает CLOUDINARY_API_SECRET. Никогда не размещайте этот секрет в клиентском компоненте (Client Component) или переменной NEXT_PUBLIC_.

Демоверсия на Vite считывает два публичных значения из .env.example:

Vite включает переменные с префиксом VITE_ в код браузера. Имя облака и неподписанный пресет предназначены для этой границы. Секрет API — нет.

Эквивалент в Next.js использует:

Публичная доставка и getCldOgImageUrl требуют имени облака. Добавляйте секрет только тогда, когда серверный маршрут подписывает загрузки или вызывает защищенный API управления. См. руководство по установке Next Cloudinary.

URL-адрес трансформации Cloudinary описывает источник, обрезку, размеры, эффекты, слои, формат и качество.

Проект создает один настроенный экземпляр Cloudinary:

Смотрите полную конфигурацию в src/lib/cloudinary.ts.

Смотрите полную конфигурацию в .

Трансформация начинается с фиксированного холста социальной карточки:

• Как это работает: fill заполняет весь холст, в то время как автоматическая гравитация (automatic gravity) выбирает область обрезки вокруг визуально важного контента. Регулировка яркости создает контраст под белым текстом.
• Зачем это нужно: каждая карточка должна иметь предсказуемые размеры и удобочитаемый шрифт, даже если исходные изображения имеют разные соотношения сторон.
• Когда использовать: используйте fit вместо fill, когда демонстрация полного исходного изображения важнее заполнения холста. Используйте значение ручной гравитации, когда редактор должен сам контролировать обрезку.

Руководство по трансформации изображений Cloudinary описывает поведение изменения размера и обрезки.

Руководство по трансформации изображений Cloudinary описывает поведение изменения размера и обрезки.

Cloudinary рассматривает текст как сгенерированный слой. Вы можете стилизовать и позиционировать этот слой так же, как наложение изображения.

Слой заголовка из сборки выглядит следующим образом:

• Как это работает: слой использует Arial, переменную величину шрифта, белый текст, блок подгонки `950 × 310`, южновластную гравитацию (southwest gravity) и явные смещения. SDK кодирует специальные символы для URL доставки.
• Зачем это нужно: блок подгонки ограничивает длинные заголовки, а гравитация и смещения удерживают текст выровненным по стабильной сетке макета.
• Когда использовать: используйте пользовательский шрифт, когда типографика бренда имеет значение. Cloudinary поддерживает загрузку пользовательских шрифтов. Проверьте каждый ожидаемый язык и длину заголовка перед публикацией.

Конструктор также добавляет метку серии и строку автора. Тот же шаблон может отображать описание, дату, категорию, цену или элемент бренда. Эта сборка сохраняет описание в метаданных страницы.

Прочитайте официальное руководство по слоям Cloudinary, параметрам текстовых слоев и руководству по текстовым оверлеям Next Cloudinary.

Прочитайте официальное руководство по слоям Cloudinary, параметрам текстовых слоев и руководству по текстовым оверлеям Next Cloudinary.

Браузерная студия применяет f_auto и q_auto.

`f_auto` выбирает поддерживаемый формат доставки на основе возможностей браузера в запросе. q_auto анализирует изображение и формат для выбора настроек сжатия. Прочтите документацию по автоматическим форматам и документацию по автоматическому качеству.

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

Студия хранит редактируемые значения в состоянии React и пересчитывает URL при изменении любого поля ввода:

• Как: React передает выбранный `public_id` и данные страницы в конструктор Cloudinary.
• Почему: Превью всегда отражает текущее состояние редактора, и каждая карточка платформы получает один и тот же URL.
• Когда: В системе управления контентом (CMS) формируйте URL на сервере из сохраненных данных поста, а не из интерактивного состояния браузера.

Проект загружает скрипт виджета загрузки Cloudinary и настраивает одно изображение за операцию:

Перед открытием виджета компонент вызывает документированный метод виджета `update`, чтобы заменить context.alt на текущий проверенный текст.

См. полную версию UploadWidget.tsx.

См. полную версию .

• Как: Cloudinary сохраняет исходный медиаресурс, теги, размещение в папках и контекстные метаданные. Обратный вызов возвращает `public_id` ресурса.
• Почему: Для последующих трансформаций необходим стабильный `public_id`, а не объект загруженного файла или локальный путь.
• Когда: Используйте неподписанный виджет для публичных демоверсий с ограниченными пресетами. Используйте подписанную загрузку для аутентифицированных инструментов публикации.

Демонстрация сохраняет возвращенные публичные идентификаторы в localStorage, а затем запрашивает эти изображения у Cloudinary после обновления. Список в браузере не является аутентифицированным поиском по Cloudinary.

Для библиотеки с несколькими пользователями добавьте маршрут сервера, который вызывает API поиска или административный API Cloudinary и проверяет доступ к папке. Храните секретный ключ API на сервере.

Метаданные Open Graph описывают общую страницу. Социальные краулеры читают такие теги, как og:title, og:description и og:image. Используйте generateMetadata в Next.js, когда эти значения зависят от параметра маршрута, записи в базе данных или ответа CMS.

Установите Next Cloudinary в приложение Next.js:

Сформируйте социальный URL из текущего поста:

Это эквивалент Next Cloudinary для конструктора URL Vite.

Ознакомьтесь с официальным руководством getCldOgImageUrl и репозитория.

Ознакомьтесь с официальным руководством getCldOgImageUrl и репозитория.

После создания imageUrl с помощью предыдущего вызова верните его как для Open Graph, так и для метаданных X:

• Как: Next.js преобразует возвращенный объект в теги <meta>, специфичные для страницы.
• Почему: Краулер получает из ответа страницы название статьи, описание, URL изображения, размеры и проверенный альтернативный текст.
• Когда: Используйте generateMetadata для страниц с App Router, метаданные которых зависят от текущего поста. Используйте статический объект `metadata`, когда все страницы в сегменте имеют одинаковые значения.

В Next.js Metadata API documentation описывается разрешение метаданных, требования к серверным компонентам и генерируемые теги.

В описывается разрешение метаданных, требования к серверным компонентам и генерируемые теги.

CldOgImage создает социальные теги на базе Cloudinary для Pages Router в Next.js:

Разместите компонент за пределами `next/head`. Он не отображает видимый элемент `<img>`. Он внедряет метаданные соцсетей в документ.

CldOgImage не поддерживает App Router. Используйте там getCldOgImageUrl с generateMetadata. В официальной документации CldOgImage указано это ограничение маршрутизатора.

Используйте наиболее простой подход, соответствующий вашей модели публикации:

Next.js документирует как статические файлы, так и сгенерированные маршруты opengraph-image.

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

Протестируйте URL трансформации перед тестированием социального краулера:

1. Запустите npm run dev.

2. Измените заголовок, автора, акцентный цвет, размер шрифта и исходный ресурс.

3. Выберите «Скопировать URL доставки».

4. Откройте URL в окне приватного просмотра браузера.

5. Убедитесь, что изображение возвращается, заголовок помещается и объект остается видимым.

6. Проверьте URL на наличие инструкций по обрезке, слоям, формату и качеству.

Протестируйте производственные метаданные Next.js по URL развернутой статьи:

Убедитесь, что:

– og:image содержит абсолютный URL Cloudinary.

– og:image:width и og:image:height соответствуют результату.

– og:image:alt содержит проверенный текст.

– twitter:card равен summary_large_image.

– URL Cloudinary возвращает код HTTP 200 без аутентификации.

Затем отправьте URL статьи в Meta Sharing Debugger и LinkedIn Post Inspector. Оба инструмента могут запросить повторное сканирование. Существующие публикации могут сохранять старые превью.

Студия Vite развертывается на Netlify с добавленным в репозиторий netlify.toml:

Перенаправление сохраняет доступность /about при прямой навигации. Netlify рекомендует использовать npm run build и dist для развертывания Vite.

Добавьте эти переменные сборки в Netlify:

После развертывания:

1. Откройте главную страницу и /about.

2. Обновите страницу /about, чтобы проверить перенаправление для одностраничного приложения.

3. Загрузите одноразовое тестовое изображение.

4. Убедитесь в правильности папки ресурсов, тегов и контекста в Cloudinary.

5. Скопируйте и откройте созданный URL трансформации.

6. Удалите одноразовый ресурс из Cloudinary по завершении тестирования.

Рабочее развертывание Vite проверяет редактор и рабочий процесс генерации изображений. Блог в продакшене также должен развернуть интеграцию метаданных Next.js и проверить сгенерированные теги на маршруте статьи.

Готовый рабочий процесс преобразует данные статьи в URL доставки Cloudinary, а затем использует метаданные Next.js для публикации этого URL для социальных краулеров. Текстовые слои поддерживают синхронизацию названия, серии и автора со страницей, в то время как трансформации доставки управляют обрезкой, размещением, форматом и качеством.

Используйте getCldOgImageUrl с App Router, CldOgImage с Pages Router и статические изображения, когда контент не меняется. Держите разрешения на загрузку и секреты API на правильной стороне границы браузера, а затем проверяйте как ответ изображения, так и сгенерированные метаданные после развертывания.

Готовы начать работу с Cloudinary? Зарегистрируйте бесплатный аккаунт и создавайте лучшие визуальные впечатления уже сегодня.

Динамическое изображение Open Graph — это социальное изображение, URL или отображаемый контент которого зависит от данных страницы. Этот проект объединяет исходный ресурс Cloudinary с названием статьи, серией, автором, типографикой и фирменным цветом.

Нет. CldOgImage поддерживает Pages Router. Используйте getCldOgImageUrl внутри generateMetadata для App Router.

Нет. Трансформации доставки создают производные версии на основе инструкций в URL. Исходный ресурс остается доступным, если только входящая трансформация во время загрузки не изменяет его.

Нет. Имя пресета отображается в коде браузера. Ограничьте пресет по формату, размеру, папке и поведению публичного идентификатора. Используйте подписанную конечную точку сервера, когда для загрузки требуется авторизация.

Превью в браузере выигрывают от автоматического выбора формата. Социальные краулеры не всегда заявляют о такой же поддержке форматов, как браузеры, поэтому getCldOgImageUrl по умолчанию использует JPEG для более широкой совместимости с краулерами.