Tạo OG Images trong Next.js — API og:image động
Tạo OG images trong Next.js bằng Dynamic API dựa trên đăng ký của FastOG — với gói đăng ký Dynamic API (tạo API key của bạn trong dashboard), và Free OG Image Tester cho phép xem trước hình ảnh trước khi bạn viết một dòng mã nào. Hướng dẫn này chỉ cho bạn cách xây dựng Open Graph images động với URL ký HMAC, trực tiếp từ Next.js App Router.
Bắt đầu nhanh
1. Tạo tiện ích ký (signer utility)
javascript
// lib/og-image-signer.js
import crypto from "crypto";
export function generateSignedOgUrl(params, options = {}) {
const {
baseUrl = "https://fastog.com/api/v1/og",
apiKey = process.env.FASTOG_API_KEY,
hmacSecret = process.env.FASTOG_HMAC_SECRET,
} = options;
if (!apiKey || !hmacSecret) {
throw new Error("Missing FASTOG_API_KEY or FASTOG_HMAC_SECRET");
}
// RFC-3986 percent-encoding: keep A-Za-z0-9-._~
const enc = (s) =>
encodeURIComponent(s).replace(
/[!'()*]/g,
(c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
);
// Every query param except the signature, INCLUDING key
const all = { ...params, key: apiKey };
// Canonical query: sorted enc(key)=enc(value) pairs joined with &
const pairs = [];
for (const [k, v] of Object.entries(all)) {
for (const vv of Array.isArray(v) ? v : [v]) {
pairs.push(`${enc(k)}=${enc(vv)}`);
}
}
pairs.sort();
const canonical = pairs.join("&");
// Sign the exact bytes the server will verify
const signature = crypto
.createHmac("sha256", hmacSecret)
.update(`GET/api/v1/og\n${canonical}`)
.digest("hex");
// Build the URL from the same pairs so bytes match the canonical form
const url = new URL(baseUrl);
for (const [k, v] of Object.entries(all)) {
for (const vv of Array.isArray(v) ? v : [v]) {
url.searchParams.append(Array.isArray(v) ? `${k}[]` : k, vv);
}
}
url.searchParams.set("s", signature);
return url.toString();
}
2. Thiết lập biến môi trường
bash
# .env.local
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
Pattern 1: Metadata API (Được khuyến nghị)
typescript
// app/blog/[slug]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
import { getPost } from "@/lib/posts";
interface PageProps {
params: Promise<{ slug: string }>;
}
export async function generateMetadata({ params }: PageProps) {
const { slug } = await params;
const post = await getPost(slug);
const ogImageUrl = generateSignedOgUrl({
template: "blog",
title: post.title,
subtitle: post.excerpt,
author: post.author.name,
});
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [
{
url: ogImageUrl,
width: 1200,
height: 630,
alt: post.title,
},
],
type: "article",
},
twitter: {
card: "summary_large_image",
images: [ogImageUrl],
},
};
}
export default async function BlogPost({ params }: PageProps) {
const { slug } = await params;
const post = await getPost(slug);
return (
<article>
<h1>{post.title}</h1>
<p>{post.excerpt}</p>
</article>
);
}
Mẫu 2: Proxy qua API Route
Sử dụng mẫu này nếu bạn muốn lưu bộ nhớ đệm (cache) cho các ảnh OG hoặc thêm logic tùy chỉnh.
typescript
// app/api/og/route.ts
import { NextRequest, NextResponse } from "next/server";
import { generateSignedOgUrl } from "@/lib/og-image-signer";
export async function GET(request: NextRequest) {
try {
const { searchParams } = new URL(request.url);
const title = searchParams.get("title");
const template = searchParams.get("template") || "default";
if (!title) {
return NextResponse.json(
{ error: "Missing title parameter" },
{ status: 400 },
);
}
const ogImageUrl = generateSignedOgUrl({
template,
title,
});
// Option 1: Redirect to FastOG
return NextResponse.redirect(ogImageUrl);
// Option 2: Fetch and return image (for caching)
// const response = await fetch(ogImageUrl);
// const imageBuffer = await response.arrayBuffer();
// return new NextResponse(imageBuffer, {
// headers: {
// 'Content-Type': 'image/png',
// 'Cache-Control': 'public, max-age=31536000, immutable',
// },
// });
} catch (error) {
console.error("OG image generation failed:", error);
return NextResponse.json(
{ error: "Failed to generate OG image" },
{ status: 500 },
);
}
}
Cách sử dụng trong các template:
typescript
<meta property="og:image" content={`/api/og?title=${encodeURIComponent(post.title)}`} />
Mẫu 3: Server Component Trực Tiếp
typescript
// app/blog/[slug]/page.tsx
import { generateSignedOgUrl } from '@/lib/og-image-signer';
export default async function BlogPost({ params }) {
const post = await getPost(params.slug);
const ogImageUrl = generateSignedOgUrl({
template: 'blog',
title: post.title,
});
return (
<article>
<head>
<meta property="og:image" content={ogImageUrl} />
<meta property="og:title" content={post.title} />
</head>
{/* ... post content ... */}
</article>
);
}
Ví dụ về Thương mại điện tử
typescript
// app/products/[id]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
export async function generateMetadata({ params }) {
const { id } = await params;
const product = await getProduct(id);
const ogImageUrl = generateSignedOgUrl({
template: "ecommerce",
title: product.name,
price: product.price,
image: product.image,
});
return {
openGraph: {
title: product.name,
description: product.description,
images: [{ url: ogImageUrl, width: 1200, height: 630 }],
type: "product",
},
};
}
Hồ sơ người dùng (Mẫu Blog)
FastOG không có mẫu profile — hãy dùng blog cho thẻ kiểu hồ sơ, truyền tên người dùng làm title, tiểu sử làm subtitle và tên làm author.
typescript
// app/users/[username]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
export async function generateMetadata({ params }) {
const { username } = await params;
const user = await getUser(username);
const ogImageUrl = generateSignedOgUrl({
template: "blog",
title: user.name,
subtitle: user.bio,
author: user.name,
});
return {
openGraph: {
title: `${user.name} - Profile`,
description: user.bio,
images: [{ url: ogImageUrl, width: 1200, height: 630 }],
type: "profile",
},
};
}
Các Lỗi Thường Gặp
Ký Khác Với Dữ Liệu Bạn Gửi
Chữ ký bao gồm GET/api/v1/og cộng với một dòng mới cộng với truy vấn chuẩn — các cặp enc(key)=enc(value) đã được sắp xếp của mọi tham số trừ s, bao gồm cả key. Hãy xây dựng URL cuối cùng từ chính các cặp đã mã hóa đó, nếu không máy chủ sẽ trả về 401 invalid_signature.
Lộ Bí Mật HMAC Trong Mã Phía Máy Khách
❌ Sai:
javascript
// In client component
const ogUrl = generateSignedOgUrl(params, {
hmacSecret: process.env.NEXT_PUBLIC_HMAC_SECRET,
});
✅ Đúng:
javascript
// In server component or API route (never expose to client)
export async function generateMetadata() {
const ogUrl = generateSignedOgUrl(params);
}