社交分享图片与图标
当有人将站点链接粘贴到 X、LinkedIn、Slack、Discord 或 WhatsApp 时,应显示包含清晰标题的大图。浏览器和手机应显示清晰的图标。
1. 检查
- App 文件夹 (
src/app/或app/),现有的favicon.ico、icon.*、apple-icon.*、opengraph-image.*、twitter-image.*。 - 根布局中的
metadataBase。如果没有它,og:image 的 URL 是相对路径,社交平台将忽略它们。 如果缺少,请添加(参见launch-seo技能,或设置metadataBase: new URL("https://your-domain.com"))。 next.config.*:output: "export"?- 品牌信息:名称、标语、主色调、Logo(优先使用 SVG)。复用
globals.css中的令牌。 - 阅读与版本匹配的文档:
node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/01-metadata/opengraph-image.mdnode_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/01-metadata/app-icons.mdnode_modules/next/dist/docs/01-app/03-api-reference/04-functions/image-response.md
2. Open Graph 图片(站点全局)
将 assets/opengraph-image.tsx 复制到 app/opengraph-image.tsx,并编辑品牌值。它导出 alt、size(1200×630)和 contentType,并使用 next/og 中的 ImageResponse 绘制图片。
分享图片的设计规则:
- 标题为 3–8 个词,至少 64px,高对比度。必须在 300px 宽的缩略图中清晰可读。
- 将重要内容保留在中心 1000×500 区域内;部分平台会裁剪边缘。
- 在角落放置品牌标记 + 域名,让用户知道链接指向何处。
- 仅使用 Flexbox:
ImageResponse支持 CSS 的子集(display: flex,无网格)。每个包含多个子元素的元素都需要display: "flex"。 - 字体:默认字体开箱即用。如需自定义字体,请使用
readFile加载.ttf/.otf/.woff文件(不能是.woff2),并通过fonts选项传递,如文档所示。 - 大小限制:Open Graph 为 8 MB,Twitter 为 5 MB。生成的 PNG 通常小于 100 KB。
twitter-image 是可选的:当它缺失时,X 会使用 Open Graph 图片。确保根元数据设置了 twitter: { card: "summary_large_image" }。
3. 每页图片(博客文章、文档、产品页面)
在动态段内添加 opengraph-image.tsx,例如 app/blog/[slug]/opengraph-image.tsx。它接收 params(一个 Promise)并可以加载文章标题;从图片文件中导出 generateStaticParams,以便每张图片都能预渲染。保持相同的模板,使所有分享看起来属于同一品牌。
这比看起来更重要:当页面在 metadata/generateMetadata 中设置了自身的 openGraph 时,它会替换父级的 openGraph 对象,导致该页面的根分享图片消失。段级别的 opengraph-image 文件(或显式的 openGraph.images)可解决此问题。
4. 图标
文件(位于 app/ 中) | 大小 | 用途 |
|---|---|---|
favicon.ico | 32×32(多尺寸也可) | 浏览器标签页,应用根目录必需 |
icon.png 或 icon.svg | 512×512 PNG 或 SVG | 现代浏览器,Android |
apple-icon.png | 180×180 | iOS 主屏幕 |
你也可以使用 ImageResponse 生成 icon.tsx / apple-icon.tsx — 参见 assets/icon.tsx。在启动前替换默认的 create-next-app 的 favicon.ico;如果没有可用的 .ico 工具,可以接受 32×32 的 icon.png 并删除旧的 favicon.ico。
5. 静态导出说明
使用 output: "export"(在 Next.js 16.4 上测试):
cacheComponents必须在静态导出时关闭,并且每个生成的图片文件(opengraph-image.tsx、icon.tsx、apple-icon.tsx)都需要export const dynamic = "force-static";,否则构建将失败。动态段还需要generateStaticParams。- 生成的图片导出时没有文件扩展名(
out/opengraph-image),因此静态主机在提供这些文件时没有Content-Type头(已在 Cloudflare Pages 上验证)。某些爬虫会拒绝它们。最佳修复方法:在运行中的站点打开/opengraph-image,保存它,然后将其提交为app/opengraph-image.png(然后删除.tsx);它将以正确的类型导出为opengraph-image.png。图标也类似(app/icon.png、app/apple-icon.png)。对于每篇文章的图片,在主机头文件(Cloudflare Pages/Netlify 上的public/_headers)中为这些路径设置Content-Type: image/png。
6. 验证
-
npm run build必须通过。构建输出会列出opengraph-image路由。 -
启动站点(
npm run start,或提供out/文件夹)并运行检查脚本(Node 18+,无依赖)。<skill-dir>是包含此 SKILL.md 的文件夹:node <skill-dir>/scripts/check-og.mjs http://localhost:3000/ http://localhost:3000/blog/some-post它会读取页面的
og:*和twitter:*标签,下载图片,并检查绝对 URL、HTTP 状态、文件大小、尺寸(1200×630)、og:image:alt和twitter:card。标签中的 localhost URL 会被报告,因为这意味着metadataBase缺失或对生产环境不正确。 -
在浏览器中打开图片 URL 并查看。检查当浏览器窗口变窄时,文本是否可读。
-
部署后,告知用户使用平台自身的工具进行测试(LinkedIn Post Inspector、Facebook Sharing Debugger)。这些工具还能刷新缓存的预览。
报告
列出已创建的图片和图标文件、检查脚本的输出,并提醒用户平台会缓存预览:更改图片后,使用上述工具重新抓取。