はじめに#

ブログ記事を SNS でシェアしたとき、OGP 画像の有無でクリック率は大きく変わります。
Astro なら satori を使ってビルド時に自動生成するのが定番ですが、
Cloudflare Pages にデプロイする日本語ブログではいくつかの罠があります。

このブログで実際に踏んだ 2 つの問題と、その解決策を紹介します。

1. sharp が Cloudflare のランタイムで動かない
2. 日本語タイトルが文字単位で折返され、文節の途中で改行される

構成の全体像#

最終的に採用したパイプラインは以下の通りです。

flowchart LR
    A["getStaticPaths()"] --> B["satori<br/>HTML → SVG"]
    B --> C["resvg<br/>SVG → PNG"]
    C --> D["dist/og/slug.png"]

ポイントは export const prerender = true を宣言し、
ビルド時に全投稿分の OGP を静的ファイルとして出力する点です。ランタイムでは一切画像生成をしません。

1
export const prerender = true;
2

3
export async function getStaticPaths() {
4
  const posts = await getCollection("posts");
5
  return posts.map((post) => ({
6
    params: { slug: post.slug },
7
    props: { post },
8
  }));
9
}

記事ページ側では、<meta property="og:image"> に /og/${slug}.png を指定しておけば、
ビルドで生成された静的ファイルがそのまま配信されます。

なぜ sharp ではダメだったのか#

Astro の OGP 画像生成で検索すると、多くの記事が satori + sharp の組み合わせを紹介しています。
僕も最初はこの構成でした。

ところが Cloudflare Pages では sharp がランタイムで動きません。
sharp は C++ の native binding に依存しており、Cloudflare の V8 Isolate 環境では実行できないからです。

prerender: true を付ければビルド時（= Node.js 環境）で実行されるため sharp でも動きますが、
この宣言を忘れると Astro は SSR ルート扱いにします。
結果として本番デプロイ後に OGP エンドポイントが 5xx を返し、SNS のクローラーが画像を取得できなくなります。

解決策は sharp を @resvg/resvg-js に置き換えることです。

1
import { Resvg } from "@resvg/resvg-js";
2

3
// satori が返した SVG 文字列を PNG に変換
4
const resvg = new Resvg(svg, {
5
  fitTo: { mode: "width", value: 1200 },
6
});
7
const png = resvg.render().asPng();

@resvg/resvg-js も native Node binding ですが、
prerender: true と組み合わせることでビルド時にしか実行されないため、ランタイム非対応の問題を完全に回避できます。

なお、native binding を含むパッケージは Astro の server bundle に巻き込まれるとビルドが失敗します。
astro.config.mjs で明示的に除外する必要があります。

1
vite: {
2
  ssr: {
3
    external: ["@resvg/resvg-js", "satori", "satori-html"],
4
  },
5
},

日本語タイトルの改行問題#

ここまでで OGP 画像は生成できるようになりましたが、日本語ブログ特有の問題が残ります。

satori のテキストレイアウトエンジンは 文字単位 で折返しを判定します。
英語なら単語境界（スペース）で自然に切れますが、日本語にはスペースによる単語区切りがないため、
「渡す」が「渡」と「す」に分断されるような不自然な改行が発生しました。

1
import { loadDefaultJapaneseParser } from "budoux";
2

3
const jpParser = loadDefaultJapaneseParser();
4

5
function estimateWidth(text: string): number {
6
  let w = 0;
7
  for (const ch of text) {
8
    w += ch.charCodeAt(0) > 0x7f ? 1 : 0.55;
9
  }
10
  return w;
11
}
12

13
function splitTitleIntoLines(title: string, fontSize: number): string[] {
14
  const maxUnits = (CONTENT_WIDTH / fontSize) * 0.95;
15
  const phrases = jpParser.parse(title);
16
  const lines: string[] = [];
17
  let current = "";
18

19
  for (const phrase of phrases) {
20
    const next = current + phrase;
21
    if (estimateWidth(next) > maxUnits && current.length > 0) {
22
      lines.push(current);
23
      current = phrase;
24
    } else {
25
      current = next;
26
    }
27
  }
28
  if (current) lines.push(current);
29

30
  return lines;
31
}

はまりポイントまとめ#

1. prerender: true を忘れると本番で壊れる
   Cloudflare Pages + Astro の組み合わせでは、native binding を使うエンドポイントには必ず prerender: true を付ける。付け忘れると開発環境では動くのに本番で 5xx になる。

2. satori は全要素に display: flex が必要
   satori のレイアウトエンジンは Yoga ベースで、すべての要素が Flexbox として評価される。display: flex を省略すると予期しないレイアウト崩れが起きる。

3. satori-html の tagged template は値を HTML エスケープする
   html`...${dynamicHtml}...` と書くと dynamicHtml 内の <div> がエスケープされてしまう。動的に生成した HTML を挿入するには、raw 文字列として渡すヘルパーが必要。

まとめ#

• Astro + Cloudflare Pages で OGP 画像を自動生成するなら、prerender: true + satori + @resvg/resvg-js がビルド時完結で安定する
• 日本語ブログでは budoux を入れるだけで改行品質が劇的に改善 される。約 30 KB の依存を追加するだけで、全記事の OGP 画像が自然な文節区切りになる
• satori 特有の制約（display: flex 必須、ZWSP の tofu 化、satori-html のエスケープ）は事前に知っておくとデバッグ時間を大幅に節約できる

まずは自分のブログの OGP エンドポイントに export const prerender = true が付いているか確認するところから始めるのがおすすめです。