Next.js Notion Starter Kit 中解决 Open Graph 图片生成问题

Next.js Notion Starter Kit 是一个基于 Notion 作为内容管理系统的博客模板项目。在使用过程中，开发者可能会遇到 Open Graph (OG) 图片无法正常显示的问题，本文将深入分析问题原因并提供解决方案。

问题现象

当用户通过社交媒体分享网站链接时，系统会自动生成预览图片。但在某些配置下，这些预览图片会显示为空白。检查页面源代码会发现，og:image 标签指向的 URL 返回的是空内容。

根本原因分析

这个问题通常由两个主要因素导致：

1. Vercel 认证设置：默认情况下，Vercel 部署的项目可能启用了认证保护，这会阻止社交媒体爬虫访问生成图片的 API 端点。

2. 域名配置错误：site.config.ts 文件中的域名设置不正确，导致图片生成服务无法正确构建完整的 URL。

解决方案

1. 禁用 Vercel 认证保护

在 Vercel 项目设置中：

• 进入项目设置页面
• 找到"认证"或"保护"相关选项
• 确保项目设置为公开访问状态
• 完成设置后需要重新部署项目使更改生效

2. 正确配置域名

在项目的 site.config.ts 配置文件中：

• 确保 domain 字段设置为完整的生产环境域名
• 格式应为 https://your-domain.com（包含协议头）
• 避免使用本地开发环境地址或临时部署地址

3. 验证配置

完成上述更改后，可以通过以下方式验证：

• 直接访问 API 端点 URL，检查是否返回有效图片
• 使用社交媒体调试工具测试链接分享效果
• 检查页面源代码确认 og:image 标签指向正确的 URL

技术实现原理

该项目使用 Next.js 的 API 路由动态生成 Open Graph 图片。当社交媒体爬虫访问页面时：

1. 爬虫解析 HTML 中的 og:image 元标签
2. 向指定的 API 端点发起请求
3. API 端点根据页面 ID 从 Notion 获取内容
4. 使用 Canvas 或其他图形库动态生成图片
5. 返回生成的图片作为响应

任何阻碍这个流程的环节都会导致图片无法正常显示。

最佳实践建议

1. 定期检查部署设置：特别是在 Vercel 上更新项目后，确认认证设置未被意外修改

2. 使用固定域名：避免频繁更改域名配置，防止社交媒体缓存旧的 OG 数据

3. 监控日志：定期检查服务器日志，及时发现并处理未授权的访问请求

4. 提供回退方案：在代码中实现默认图片逻辑，当动态生成失败时使用预设图片

通过以上措施，可以确保 Next.js Notion Starter Kit 项目中的 Open Graph 图片功能稳定可靠地工作，提升社交媒体分享体验。