362 lines
10 KiB
Markdown
362 lines
10 KiB
Markdown
# 🖼️ Интеграция @vercel/og с Quoter Proxy
|
||
|
||
## 📋 Обзор
|
||
|
||
`@vercel/og` - это мощная библиотека для генерации динамических OpenGraph изображений на Edge Runtime. Quoter теперь поддерживает интеграцию с @vercel/og для создания красивых социальных превью.
|
||
|
||
## 🔄 Изменения в архитектуре
|
||
|
||
### Удалённая функциональность (Legacy)
|
||
- ❌ `src/overlay.rs` - удалена встроенная логика наложения текста
|
||
- ❌ `src/Muller-Regular.woff2` - удалён встроенный шрифт
|
||
- ❌ `imageproc`, `ab_glyph` dependencies - удалены из Cargo.toml
|
||
- ❌ Параметр `s=<shout_id>` в API - больше не поддерживается
|
||
|
||
### Новая архитектура
|
||
- ✅ @vercel/og обрабатывает генерацию OpenGraph изображений
|
||
- ✅ Quoter выступает как proxy для статических файлов
|
||
- ✅ Improved caching и performance optimization
|
||
|
||
## 🚀 Настройка @vercel/og
|
||
|
||
### 1. Установка пакета
|
||
|
||
```bash
|
||
npm install @vercel/og
|
||
# или
|
||
yarn add @vercel/og
|
||
```
|
||
|
||
### 2. Базовый пример использования
|
||
|
||
```typescript
|
||
import { ImageResponse } from '@vercel/og'
|
||
|
||
export default function handler(req: Request) {
|
||
return new ImageResponse(
|
||
(
|
||
<div
|
||
style={{
|
||
fontSize: 128,
|
||
background: 'white',
|
||
width: '100%',
|
||
height: '100%',
|
||
display: 'flex',
|
||
textAlign: 'center',
|
||
alignItems: 'center',
|
||
justifyContent: 'center',
|
||
}}
|
||
>
|
||
Hello world!
|
||
</div>
|
||
),
|
||
{
|
||
width: 1200,
|
||
height: 600,
|
||
},
|
||
)
|
||
}
|
||
```
|
||
|
||
## 🔗 Интеграция с Quoter Proxy
|
||
|
||
### Сценарий использования
|
||
1. @vercel/og генерирует динамические OpenGraph изображения
|
||
2. Результат сохраняется через Quoter API
|
||
3. Quoter обслуживает изображения с кэшированием и оптимизацией
|
||
|
||
### Настройка Endpoint для @vercel/og
|
||
|
||
```typescript
|
||
// pages/api/og/[...slug].ts
|
||
import { ImageResponse } from '@vercel/og'
|
||
import { NextRequest } from 'next/server'
|
||
|
||
export const config = {
|
||
runtime: 'edge',
|
||
}
|
||
|
||
export default async function handler(req: NextRequest) {
|
||
try {
|
||
const { searchParams } = new URL(req.url)
|
||
|
||
// Получение параметров
|
||
const title = searchParams.get('title') ?? 'Default Title'
|
||
const description = searchParams.get('description') ?? 'Default Description'
|
||
const imageUrl = searchParams.get('image') // URL изображения из Quoter
|
||
|
||
// Загрузка изображения через Quoter proxy
|
||
let backgroundImage = null
|
||
if (imageUrl) {
|
||
try {
|
||
const imageResponse = await fetch(imageUrl)
|
||
const imageBuffer = await imageResponse.arrayBuffer()
|
||
backgroundImage = `data:image/jpeg;base64,${Buffer.from(imageBuffer).toString('base64')}`
|
||
} catch (error) {
|
||
console.error('Failed to load image from Quoter:', error)
|
||
}
|
||
}
|
||
|
||
return new ImageResponse(
|
||
(
|
||
<div
|
||
style={{
|
||
background: backgroundImage
|
||
? `url(${backgroundImage})`
|
||
: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
|
||
backgroundSize: 'cover',
|
||
backgroundPosition: 'center',
|
||
width: '100%',
|
||
height: '100%',
|
||
display: 'flex',
|
||
flexDirection: 'column',
|
||
alignItems: 'center',
|
||
justifyContent: 'center',
|
||
fontFamily: 'system-ui',
|
||
}}
|
||
>
|
||
{/* Overlay для читаемости */}
|
||
<div
|
||
style={{
|
||
position: 'absolute',
|
||
top: 0,
|
||
left: 0,
|
||
right: 0,
|
||
bottom: 0,
|
||
backgroundColor: 'rgba(0, 0, 0, 0.4)',
|
||
}}
|
||
/>
|
||
|
||
{/* Контент */}
|
||
<div
|
||
style={{
|
||
display: 'flex',
|
||
flexDirection: 'column',
|
||
alignItems: 'center',
|
||
zIndex: 1,
|
||
padding: '40px',
|
||
textAlign: 'center',
|
||
}}
|
||
>
|
||
<h1
|
||
style={{
|
||
fontSize: '72px',
|
||
fontWeight: 'bold',
|
||
color: 'white',
|
||
margin: 0,
|
||
marginBottom: '20px',
|
||
textShadow: '2px 2px 4px rgba(0, 0, 0, 0.8)',
|
||
}}
|
||
>
|
||
{title}
|
||
</h1>
|
||
<p
|
||
style={{
|
||
fontSize: '36px',
|
||
color: '#f1f5f9',
|
||
margin: 0,
|
||
textShadow: '1px 1px 2px rgba(0, 0, 0, 0.8)',
|
||
}}
|
||
>
|
||
{description}
|
||
</p>
|
||
</div>
|
||
</div>
|
||
),
|
||
{
|
||
width: 1200,
|
||
height: 630,
|
||
}
|
||
)
|
||
} catch (e: any) {
|
||
console.log(`${e.message}`)
|
||
return new Response(`Failed to generate the image`, {
|
||
status: 500,
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📤 Сохранение сгенерированных изображений в Quoter
|
||
|
||
### Пример интеграции
|
||
|
||
```typescript
|
||
// utils/saveToQuoter.ts
|
||
export async function saveOgImageToQuoter(
|
||
imageBuffer: Buffer,
|
||
filename: string,
|
||
token: string
|
||
): Promise<string> {
|
||
const formData = new FormData()
|
||
const blob = new Blob([imageBuffer], { type: 'image/png' })
|
||
formData.append('file', blob, filename)
|
||
|
||
const response = await fetch('https://quoter.staging.discours.io/', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
},
|
||
body: formData,
|
||
})
|
||
|
||
if (!response.ok) {
|
||
throw new Error(`Failed to upload to Quoter: ${response.statusText}`)
|
||
}
|
||
|
||
const result = await response.text()
|
||
return result // URL загруженного файла
|
||
}
|
||
|
||
// Использование
|
||
async function generateAndSaveOgImage(title: string, description: string, token: string) {
|
||
// Генерация изображения через @vercel/og
|
||
const ogResponse = await fetch(`/api/og?title=${encodeURIComponent(title)}&description=${encodeURIComponent(description)}`)
|
||
const imageBuffer = Buffer.from(await ogResponse.arrayBuffer())
|
||
|
||
// Сохранение в Quoter
|
||
const filename = `og-${Date.now()}.png`
|
||
const quoterUrl = await saveOgImageToQuoter(imageBuffer, filename, token)
|
||
|
||
return quoterUrl
|
||
}
|
||
```
|
||
|
||
## 🎨 Расширенные возможности
|
||
|
||
### Кастомные шрифты
|
||
|
||
```typescript
|
||
// Загрузка шрифтов
|
||
const font = fetch(
|
||
new URL('./assets/Muller-Regular.woff', import.meta.url)
|
||
).then((res) => res.arrayBuffer())
|
||
|
||
// Использование в ImageResponse
|
||
return new ImageResponse(
|
||
<div style={{ fontFamily: 'Muller' }}>
|
||
Custom font text
|
||
</div>,
|
||
{
|
||
width: 1200,
|
||
height: 630,
|
||
fonts: [
|
||
{
|
||
name: 'Muller',
|
||
data: await font,
|
||
style: 'normal',
|
||
},
|
||
],
|
||
}
|
||
)
|
||
```
|
||
|
||
### Динамическая загрузка изображений из Quoter
|
||
|
||
```typescript
|
||
async function loadQuoterImage(imageId: string): Promise<string> {
|
||
const quoterUrl = `https://quoter.staging.discours.io/${imageId}`
|
||
|
||
try {
|
||
const response = await fetch(quoterUrl)
|
||
if (!response.ok) throw new Error(`HTTP ${response.status}`)
|
||
|
||
const buffer = await response.arrayBuffer()
|
||
return `data:image/jpeg;base64,${Buffer.from(buffer).toString('base64')}`
|
||
} catch (error) {
|
||
console.error('Failed to load image from Quoter:', error)
|
||
return '' // fallback
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 Конфигурация Quoter для @vercel/og
|
||
|
||
### Environment Variables
|
||
|
||
```bash
|
||
# .env.local
|
||
QUOTER_API_URL=https://quoter.staging.discours.io
|
||
QUOTER_AUTH_TOKEN=your_jwt_token_here
|
||
```
|
||
|
||
### Типы для TypeScript
|
||
|
||
```typescript
|
||
// types/quoter.ts
|
||
export interface QuoterUploadResponse {
|
||
url: string
|
||
filename: string
|
||
size: number
|
||
contentType: string
|
||
}
|
||
|
||
export interface OgImageParams {
|
||
title: string
|
||
description?: string
|
||
backgroundImage?: string
|
||
template?: 'default' | 'article' | 'profile'
|
||
}
|
||
```
|
||
|
||
## 📊 Performance & Caching
|
||
|
||
### Оптимизация производительности
|
||
- ✅ @vercel/og работает на Edge Runtime
|
||
- ✅ Quoter обеспечивает кэширование с ETag
|
||
- ✅ Автоматическое сжатие изображений
|
||
- ✅ CDN-дружественные HTTP заголовки
|
||
|
||
### Рекомендации по кэшированию
|
||
|
||
```typescript
|
||
// Добавление cache headers для OG изображений
|
||
export default function handler(req: NextRequest) {
|
||
const imageResponse = new ImageResponse(/* ... */)
|
||
|
||
// Кэширование на 1 день
|
||
imageResponse.headers.set('Cache-Control', 'public, max-age=86400, s-maxage=86400')
|
||
imageResponse.headers.set('CDN-Cache-Control', 'public, max-age=86400')
|
||
|
||
return imageResponse
|
||
}
|
||
```
|
||
|
||
## 🚀 Deployment
|
||
|
||
### Vercel
|
||
1. Deploy @vercel/og endpoints на Vercel
|
||
2. Configure Quoter URL в environment variables
|
||
3. Set up proper CORS если нужно
|
||
|
||
### Standalone
|
||
1. Use Next.js standalone mode
|
||
2. Configure Quoter integration
|
||
3. Deploy где угодно с Node.js support
|
||
|
||
## 🔍 Troubleshooting
|
||
|
||
### Распространённые проблемы
|
||
|
||
1. **"Failed to load image from Quoter"**
|
||
- Проверьте доступность Quoter API
|
||
- Убедитесь в правильности токена авторизации
|
||
|
||
2. **"Font loading failed"**
|
||
- Убедитесь, что шрифты доступны в build time
|
||
- Используйте правильные MIME types
|
||
|
||
3. **"Image generation timeout"**
|
||
- Оптимизируйте сложность layout
|
||
- Уменьшите размер внешних ресурсов
|
||
|
||
## 📚 Дополнительные ресурсы
|
||
|
||
- [Vercel OG Documentation](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation)
|
||
- [Quoter API Reference](./api-reference.md)
|
||
- [Performance Best Practices](./monitoring.md)
|
||
|
||
---
|
||
|
||
💋 **Упрощение через разделение ответственности**: @vercel/og занимается генерацией, Quoter - хранением и доставкой.
|