Не работает Open Graph изображение в Next.js

Почему превью Next.js отсутствует или отображается некорректно

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

• Страница переопределяет openGraph и теряет изображение. Метаданные из макетов и страниц объединяются поверхностно (shallow merge), поэтому объект openGraph страницы полностью заменяет openGraph макета, включая изображение.

• Файл изображения слишком велик. Размер opengraph-image должен быть менее 8 МБ, а twitter-image — менее 5 МБ, иначе сборка завершится с ошибкой.

• Вы тестировали на localhost или на защищенном превью-деплое. Платформы выполняют запросы со своих собственных серверов и не могут получить к нему доступ.

• Платформа закешировала более ранний деплой. Обновите кеш после исправления.

Как это исправить

1. В app/layout.tsx задайте metadataBase: new URL('https://your-domain.com').

2. Когда страница задает openGraph, укажите images заново или добавьте родительские изображения через spread-оператор из generateMetadata.

3. Или добавьте файл opengraph-image.png в сегмент маршрута. Next.js автоматически добавит og:image, его тип, ширину и высоту.

4. Для сгенерированных изображений используйте ImageResponse из next/og с параметром size = { width: 1200, height: 630 }.

5. Выполните деплой, затем проверьте публичный URL с помощью инструмента проверки метатегов.

Теги, которые должен выводить Next.js

• og:title, og:description, og:url

• og:image с og:image:width, og:image:height и og:image:type

• og:image:alt из opengraph-image.alt.txt

• twitter:card и twitter:image (абсолютный URL)

Вы можете написать их вручную с помощью генератора метатегов и сравнить их с вашей сборкой.

Правила для размеров изображений

• opengraph-image: .jpg, .jpeg, .png или .gif, не более 8 МБ

• twitter-image: те же типы, не более 5 МБ

• 1200 x 630 px — размер, который Next.js использует в своих примерах

Потоковая передача метаданных и краулеры

Более новые версии Next.js могут передавать метаданные из generateMetadata в body в потоковом режиме. Для ботов с ограниченной поддержкой HTML, таких как facebookexternalhit, Next.js по-прежнему блокирует рендеринг и помещает теги в head. Он определяет таких ботов по User-Agent. Вы можете переопределить этот список с помощью параметра htmlLimitedBots в next.config.

Как принудительно обновить превью

Next.js не может очистить кеш сторонней платформы. После деплоя обновите кеш на каждой платформе: Post Inspector для LinkedIn, Sharing Debugger для Facebook, новая строка запроса для X, Slack и Discord. В инструменте обновления собраны все эти ссылки.

Источники

• Next.js generateMetadata

• opengraph-image и twitter-image