用途
og-images 用于指导在 Next.js 项目中创建 OpenGraph 和 Twitter 分享图片,基于 next/og 的 ImageResponse 生成动态图片。目标尺寸为 OpenGraph 1200x630、Twitter 1200x600。
主要能力
- 支持两种实现方式:基于文件的路由(app/opengraph-image.tsx)适合构建时标题已知的静态页面;API 路由(app/api/og/route.tsx)适合动态内容(博客文章、CMS),可通过查询参数传入 slug 和/或 title。
- 两种方式均使用 export const runtime = "edge"。
- 文件命名约定:opengraph-image.tsx 用于 Facebook、LinkedIn、iMessage(1200x630);twitter-image.tsx 用于 Twitter/X 卡片(1200x600);app/api/og/route.tsx 为动态 API 路由(1200x630)。基于文件的路由需放在对应路由目录下,例如 /about 对应 app/about/opengraph-image.tsx。
- 布局模式:使用 flexDirection: "column" 配合 justifyContent: "space-between" 分隔内容与品牌信息;标题和副标题(如作者名)置于左上角堆叠的 flex 列中;标题大号、粗体/中等字重、深色;副标题同尺寸或更小、更轻字重、柔和颜色(如 #888);文本左对齐并使用 textWrap: "balance",用 maxWidth 限制宽度;大尺寸下使用 letterSpacing: "-0.02em" 营造紧凑编辑感;1200x630 下内边距 48px 效果良好。
- 头像/Logo(可选):若项目有头像或 Logo,放在右下角,使用 justifyContent: "flex-end" 的 flex 容器;通过 fetch + arrayBuffer 加载图片,转换为 base64 data URI 作为 src;圆形头像使用 borderRadius: "50%";将已加载资源缓存到 Map 中避免重复请求。
- 自定义字体:从 public/fonts/ 加载 .ttf 文件,使用 new URL("../../../public/fonts/YourFont.ttf", import.meta.url);将 ArrayBuffer 通过 fonts 选项传给 ImageResponse;首次加载后缓存字体 buffer;fonts 配置中的字重需与实际字体文件字重匹配。
- 标题大小写:若标题来自 CMS,应用智能标题大小写——小词(a、an、the、and、but、for、in、of 等)小写,除非位于首尾;品牌名始终正确大写(WordPress、JavaScript、GitHub、macOS 等);已知缩写大写(AI、API、CSS、HTML、UI、UX);连字符词各部分独立大写。
- 元数据集成:在 generateMetadata() 中引用 OG 路由,例如 openGraph.images 设为 [
/api/og?slug=${params.slug}];静态页面可直接传标题:/api/og?title=About。
使用方式
Satori 规则(next/og 渲染引擎的硬性要求):
- 每个元素都需要 display: "flex",这是唯一的布局模式。
- 仅使用内联样式,不支持 CSS 类、外部样式表或 CSS 变量。
- 所有文本必须放在具有显式样式属性的元素中。
- 使用十六进制颜色,不支持 rgb()、hsl() 或 CSS 变量。
- 旧版本不支持 gap,使用前需测试,可回退到 margin。
常见问题与解决:
- 文本不渲染:为文本包裹元素添加 display: "flex"。
- 布局错乱:确保所有容器都有 display: "flex"。
- 颜色错误:使用十六进制颜色,而非 CSS 变量。
- 字体未加载:检查路由文件到 public/fonts/ 的相对路径。
- 图片不显示:转换为 base64 data URI,不要使用相对路径。
测试:开发期间可直接在浏览器访问路由预览,例如 http://localhost:3000/api/og?title=Hello+World;构建后验证路由在构建输出中注册为动态(f 前缀)。
适用场景
适用于使用 Next.js 且需要为页面、博客文章或 CMS 内容生成动态 OpenGraph 和 Twitter 分享图的开发者。
限制
该技能依赖 next/og 的 ImageResponse 与 Satori 渲染引擎,必须遵守上述 Satori 硬性规则。资料未提供其他平台支持、收费或价格信息。