JavaScript 中的 OG 圖片

使用 FastOG API 在 JavaScript 中生成 og:image — 需搭配 Dynamic API 訂閱方案（請在儀表板中建立您的 API 金鑰），以訂閱為基礎，並透過 HMAC 確保安全。本指南將示範如何建立一個簽署工具（signer utility），用於產生 HMAC 簽章的 OG 圖片 URL，並即時渲染動態的 Open Graph 圖片。在發布前，請先試用免費的 OG 圖片測試工具（Free OG Image Tester）進行預覽。

快速開始

目標：在 5 分鐘內產生帶有簽章的 OG 圖片 URL。

步驟 1：安裝相依套件

bash

npm install crypto  # Built-in, no install needed

步驟 2：建立簽章工具（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();
}

步驟 3：在您的應用程式中使用

javascript

// app/blog/[slug]/page.jsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";

export async function generateMetadata({ params }) {
    const post = await getPost(params.slug);

    const ogImageUrl = generateSignedOgUrl({
        template: "blog",
        title: post.title,
        subtitle: post.excerpt,
    });

    return {
        openGraph: {
            images: [ogImageUrl],
        },
    };
}

步驟 4：測試

簽章工具是一個 ES 模組（import/export），因此請使用動態 import()：

bash

node -e "
import('./lib/og-image-signer.js').then(({ generateSignedOgUrl }) => {
    console.log(generateSignedOgUrl({ title: 'Test' }));
});
"

Next.js App Router

模式 1：Metadata API（建議使用）

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,
        // Optional: customize colors
        theme: "indigo",
    });

    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],
        },
    };
}

模式 2：API 路由代理

如果您想要快取 OG 圖片或加入自訂邏輯，請使用此模式。

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 },
            );
        }

        // Generate signed URL
        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 },
        );
    }
}

使用方式：

typescript

// In your component
<meta property="og:image" content={`/api/og?title=${encodeURIComponent(post.title)}`} />

模式 3：伺服器元件直接使用

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>
    );
}

Next.js Pages Router

typescript

// pages/blog/[slug].tsx
import { generateSignedOgUrl } from '@/lib/og-image-signer';
import { GetStaticProps, GetStaticPaths } from 'next';

interface BlogPostProps {
    post: Post;
    ogImageUrl: string;
}

export default function BlogPost({ post, ogImageUrl }: BlogPostProps) {
    return (
        <>
            <Head>
                <meta property="og:image" content={ogImageUrl} />
                <meta property="og:title" content={post.title} />
                <meta property="og:description" content={post.excerpt} />
            </Head>
            <article>
                <h1>{post.title}</h1>
                <p>{post.excerpt}</p>
            </article>
        </>
    );
}

export async function getStaticPaths() {
    // Generate paths...
}

export async function getStaticProps({ params }) {
    const post = await getPost(params.slug);

    const ogImageUrl = generateSignedOgUrl({
        template: 'blog',
        title: post.title,
        subtitle: post.excerpt,
    });

    return {
        props: {
            post,
            ogImageUrl,
        },
    };
}

Express.js 後端

設定

bash

npm install express crypto

實作

javascript

// app.js
import express from "express";
import crypto from "crypto";
import { URL } from "url";

const app = express();

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;

    // 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();
}

// Blog post route
app.get("/blog/:slug", async (req, res) => {
    const post = await getPost(req.params.slug);

    const ogImageUrl = generateSignedOgUrl({
        template: "blog",
        title: post.title,
        subtitle: post.excerpt,
    });

    res.render("blog/post", {
        post,
        ogImageUrl,
    });
});

// API endpoint for dynamic OG images
app.get("/api/og", (req, res) => {
    const { title, template = "default" } = req.query;

    if (!title) {
        return res.status(400).json({ error: "Missing title" });
    }

    const ogImageUrl = generateSignedOgUrl({
        template,
        title,
    });

    res.json({ ogImageUrl });
});

app.listen(3000, () => {
    console.log("Server running on port 3000");
});

EJS 範本

ejs

<!-- views/blog/post.ejs -->
<!DOCTYPE html>
<html>
<head>
    <meta property="og:image" content="<%= ogImageUrl %>" />
    <meta property="og:title" content="<%= post.title %>" />
    <meta property="og:description" content="<%= post.excerpt %>" />
</head>
<body>
    <h1><%= post.title %></h1>
</body>
</html>

Vanilla Node.js

javascript

// og-signer.js
const crypto = require("crypto");
const { URL } = require("url");

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;

    // 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();
}

module.exports = { generateSignedOgUrl };

使用方式：

javascript

// index.js
const { generateSignedOgUrl } = require("./og-signer");

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: "My Blog Post",
});

console.log("OG Image URL:", ogUrl);

前端整合模式

模式 1：靜態網站生成（SSG）

適用於：部落格文章、產品頁面、不常變動的內容。

typescript

// Generate at build time
export async function generateStaticParams() {
    const posts = await getAllPosts();
    return posts.map((post) => ({ slug: post.slug }));
}

export async function generateMetadata({ params }) {
    const post = await getPost(params.slug);

    return {
        openGraph: {
            images: [generateSignedOgUrl({ title: post.title })],
        },
    };
}

模式 2：伺服器端渲染（SSR）

適用於：動態內容、使用者專屬頁面。

typescript

export default async function Page({ params }) {
    const data = await fetchData(params.id);
    const ogImageUrl = generateSignedOgUrl({ title: data.title });

    return (
        <>
            <Head>
                <meta property="og:image" content={ogImageUrl} />
            </Head>
            <Content data={data} />
        </>
    );
}

模式 3：用戶端備援

當伺服器端生成不可行時使用。

typescript

'use client';

import { useEffect, useState } from 'react';

export default function ShareButtons({ post }) {
    const [ogImageUrl, setOgImageUrl] = useState<string | null>(null);

    useEffect(() => {
        // Fetch from your API that generates signed URLs
        fetch(`/api/og?title=${encodeURIComponent(post.title)}`)
            .then(res => res.json())
            .then(data => setOgImageUrl(data.ogImageUrl));
    }, [post.title]);

    const shareUrl = ogImageUrl || '/fallback-og.png';

    return (
        <div>
            <button onClick={() => shareToTwitter(shareUrl)}>
                Share on Twitter
            </button>
        </div>
    );
}

⚠️ 警告：用戶端生成意味著社交爬蟲無法看到動態的 OG 圖片。請盡可能使用 SSR/SSG。

測試與除錯

單元測試

javascript

// __tests__/og-image-signer.test.js
import { generateSignedOgUrl } from "../lib/og-image-signer";

describe("generateSignedOgUrl", () => {
    const mockParams = {
        title: "Test Post",
        template: "blog",
    };

    const mockOptions = {
        apiKey: "sk_test1234567890",
        hmacSecret: "a".repeat(64),
    };

    it("generates a valid URL", () => {
        const url = generateSignedOgUrl(mockParams, mockOptions);
        expect(url).toMatch(/^https:\/\/fastog\.com\/api\/v1\/og\?/);
        expect(url).toContain("key=sk_test");
        expect(url).toContain("s=");
    });

    it("includes all params", () => {
        const url = generateSignedOgUrl(mockParams, mockOptions);
        const parsed = new URL(url);
        expect(parsed.searchParams.get("title")).toBe("Test Post");
        expect(parsed.searchParams.get("template")).toBe("blog");
    });

    it("throws without API key", () => {
        expect(() => generateSignedOgUrl(mockParams, {})).toThrow();
    });
});

手動測試

bash

# 1. Generate URL (ES module — use dynamic import)
node -e "
import('./lib/og-image-signer.js').then(({ generateSignedOgUrl }) => {
    const url = generateSignedOgUrl({ title: 'Test' });
    console.log(url);
});
"

# 2. Test with curl
curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<sig>"

# 3. Check response headers
curl -I "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<sig>"

除錯模式

javascript

function generateSignedOgUrl(params, options = {}) {
    const debug = options.debug || process.env.DEBUG_OG === "true";

    // ... existing code ...

    if (debug) {
        console.log("OG URL Debug:", {
            baseUrl,
            canonical,
            apiKey,
            signature,
            finalUrl: url.toString(),
        });
    }

    return url.toString();
}

常見陷阱

1. 在客戶端程式碼中暴露 HMAC 密鑰

❌ 錯誤：

javascript

// In client component
const ogUrl = generateSignedOgUrl(params, {
    hmacSecret: process.env.NEXT_PUBLIC_HMAC_SECRET,
});

✅ 正確：

javascript

// In server component or API route
export async function generateMetadata() {
    const ogUrl = generateSignedOgUrl(params);
    // ...
}

2. 未處理 URL 編碼

❌ 錯誤：

javascript

const url = `${baseUrl}?title=${params.title}&key=${apiKey}`;

✅ 正確：

javascript

const url = new URL(baseUrl);
url.searchParams.set("title", params.title);
url.searchParams.set("key", apiKey);

3. 簽署的位元組與實際傳送的內容不一致

簽章涵蓋 GET/api/v1/og 加上一個換行符號，再加上正規化查詢字串——即所有參數（s 除外，包含 key）經排序後的 enc(key)=enc(value) 鍵值對。請使用相同的編碼鍵值對來建構最終 URL，否則伺服器將回傳 401 invalid_signature。

環境變數

bash

# .env.local
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
FASTOG_BASE_URL=https://fastog.com/api/v1/og

typescript

// lib/env.ts
import { z } from "zod";

const envSchema = z.object({
    FASTOG_API_KEY: z.string().startsWith("sk_"),
    FASTOG_HMAC_SECRET: z.string().length(64),
    FASTOG_BASE_URL: z
        .string()
        .url()
        .optional()
        .default("https://fastog.com/api/v1/og"),
});

export const env = envSchema.parse(process.env);

完整 API 參考文件

React 教學
SvelteKit 教學
Vue/Nuxt 教學
Astro 教學
快速入門
SDK
代理整合
文件
免費 OG 圖片測試工具

JavaScript 中的 OG 圖片

目錄

快速開始

步驟 1：安裝相依套件

步驟 2：建立簽章工具（Signer Utility）

步驟 3：在您的應用程式中使用

步驟 4：測試

Next.js App Router

模式 1：Metadata API（建議使用）

模式 2：API 路由代理

模式 3：伺服器元件直接使用

Next.js Pages Router

Express.js 後端

設定

實作

EJS 範本

Vanilla Node.js

前端整合模式

模式 1：靜態網站生成（SSG）

模式 2：伺服器端渲染（SSR）

模式 3：用戶端備援

測試與除錯

單元測試

手動測試

除錯模式

常見陷阱

1. 在客戶端程式碼中暴露 HMAC 密鑰

2. 未處理 URL 編碼

3. 簽署的位元組與實際傳送的內容不一致

環境變數

後續步驟

完整 API 參考文件

相關連結