企业官网建设流程全解析

• 前端

本文以 AstroPaper 博客主题的**动态 OG 图片（Dynamic OG Image）**功能为主线，讲解它从 v1.4.0 引入、到 v6 依托 Astro Fonts 字体管线重构的完整演进与实现原理，并给出字体配置、开关控制等实战操作。读完本文，你将理解动态 OG 图片在何时生成、由哪些元素构成、如何解决非拉丁字符缺字问题，以及如何在大规模站点上权衡构建开销并安全关闭该功能。

OG 图片（OG image，即 Social Image，社交分享图）对社交媒体的传播效果至关重要：当你在 Facebook、Discord 等平台分享网站链接时，平台展示的那张预览图就是 OG 图片。Twitter 使用的社交图片严格来说不叫 OG image，但本文沿用 AstroPaper 文档的约定，将所有类型的社交分享图统称为 OG 图片。AstroPaper 通过satori+sharp在构建期为符合条件的文章自动生成独一无二的 OG 图片，让每篇文章的分享预览不再千篇一律。

静态默认 OG 图片：旧方案及其局限

在动态 OG 图片出现之前，AstroPaper 已经提供了两种为文章设置 OG 图片的途径：

1. 文章级 frontmatter 指定：作者可以在文章 frontmatter 中通过ogImage字段显式指定一张图片。根据 adding-new-post.mdx 的说明，该字段支持远程 URL（如https://example.org/remote-image.png）或相对于当前文章目录的本地图片路径。
2. 站点级默认兜底：即使作者不写ogImage，站点级默认 OG 图片也会作为兜底，例如仓库中的 public/default-og.jpg。

旧方案的问题在于默认图片是静态的：所有未在 frontmatter 指定ogImage的文章，无论标题、内容如何不同，最终都会使用同一张默认图。在信息流中，多篇不同文章共享同一张预览图，辨识度和传播效果都会大打折扣。

从源码看，这条兜底链路的实现在 src/utils/resolveDefaultOgImagePath.ts：它要求site.ogImage必须是public/下的单个文件名（含..、/、\都会直接抛错，防止路径穿越）；当features.dynamicOgImage开启时，优先使用public/{site.ogImage}（若存在），否则回退到自动生成的/og.png；当功能关闭时，则强制要求该文件存在，否则构建会报错。最终的<meta property="og:image">由 src/layouts/Layout.astro 输出。

动态 OG 图片：核心思路与实现原理

动态 OG 图片让作者无需为每篇文章手动准备 ogImage，同时避免了所有文章共用同一张兜底图的尴尬。它最早在 AstroPaper v1.4.0 引入，核心技术栈是：

• Satori：Vercel 开源的 HTML/CSS → SVG 渲染库，负责按给定的 JSX 风格元素树渲染出 SVG；
• Sharp：高性能图像处理库，负责把 SVG 转码为 PNG。

在 AstroPaper v6+ 中，整体思路保持不变（Satori 渲染 SVG，再经 Sharp 产出 PNG），但字体来源发生了重要变化：字体不再单独下载管理，而是直接取自 Astro 的Fonts 配置，并通过experimental_getFontFileURL()（Astro 6.2 起引入的 API）获取字体文件 URL，使 OG 图片生成与站点的字体管线复用同一套配置。这一设计直接解决了旧版本中中文字体、日文字体等非拉丁字符缺字的问题（详见下文"非拉丁字符问题"一节）。

在项目依赖 package.json 中可以看到satori ^0.26.0与sharp ^0.34.5，二者配合 Astro^6.3.3使用。

哪些文章会生成动态 OG 图片

根据官方文档，动态 OG 图片只在构建时为同时满足以下两个条件的文章生成：

• frontmatter不包含ogImage；
• 不是draft 草稿。

这一筛选逻辑在 src/pages/posts/[...slug]/index.png.ts 的getStaticPaths()中得到了源码级印证：

export async function getStaticPaths() { if (!config.features.dynamicOgImage) { return []; } const posts = await getCollection("posts").then(p => p.filter(({ data }) => !data.draft && !data.ogImage) ); return posts.map(post => ({ params: { slug: getPostSlug(post.id, post.filePath) }, props: post, })); }

也就是说，index.png.ts通过getStaticPaths预先枚举出"非草稿且无自定义 ogImage"的文章集合，然后为每个 slug 生成一张 PNG 端点。这些图片在文章页中的引用方式，见 src/pages/posts/[...slug]/index.astro：当文章没有 frontmatter ogImage 且config.features.dynamicOgImage开启时，OG 图片 URL 会被构造成${postUrl}/index.png（即每篇文章路径下的index.png），再交给PostLayout输出到页面 meta 中。

动态 OG 图片的构成：标题、作者与站点名

根据官方文档，动态 OG 图片包含三要素：博客文章标题、作者名和站点标题。其中作者名和站点标题分别取自 astro-paper.config.ts 中的site.author与site.title，文章标题则取自该篇 post frontmatter 的title字段。

在源码中可以看到两种动态 OG 图片的布局细节：

• 站点级动态 OG 图（src/pages/og.png.ts）：居中大字渲染config.site.title（72px 加粗），下方渲染config.site.description（28px），右下角显示config.site.url的主机名。它作为站点默认图，在public/default-og.jpg缺失且动态功能开启时由resolveDefaultOgImagePath兜底引用为/og.png。
• 文章级动态 OG 图（src/pages/posts/[...slug]/index.png.ts）：同样以 72px 加粗渲染props.data.title（即文章标题），底部左侧为by {作者名}（作者名加粗），底部右侧为config.site.title。外层还有两层黑框 + 浅灰底纹的"卡片"装饰结构，尺寸统一为1200 × 630，即社交平台通用的 OG 图片推荐比例。

两个文件共用同一套 Satori 渲染流程：通过getFontPathByWeight从fontData["--font-google-sans-code"]中分别取出400（常规）与700（粗体）两种字重的字体文件路径，再fetch其 URL 得到二进制数据，以embedFont: true嵌入 SVG；随后sharp(Buffer.from(svg)).png().toBuffer()转出 PNG，并以Content-Type: image/png返回。

非拉丁字符问题：切换字体族并同时加载 400 与 700 字重

默认情况下，包含非拉丁字符的标题无法正确显示——Satori 的字体引擎需要对应的字形才能渲染中文、日文、韩文等字符。在 AstroPaper v6 中，动态 OG 图片的字体文件来自 Astro 的Fonts 配置（astro.config.ts），并注册给 Satori 使用。

要修复缺字（tofu / 方块字）问题，官方给出的做法是：将 Google Fonts 字体族切换为覆盖你写作系统（writing system）的字体，并且务必在配置中同时包含400与700两种字重——因为 Satori 使用独立的缓冲区分别处理常规字重与粗体字重，只配置一种会导致另一种字重下字形缺失。

以覆盖日语字符为例（来自官方文档，可按受众语言自行调整）：

// astro.config.ts import { defineConfig, fontProviders } from "astro/config"; export default defineConfig({ fonts: [ { // Example: Japanese coverage (pick what you need for your audience) name: "Noto Sans JP", cssVariable: "--font-google-sans-code", provider: fontProviders.google(), fallbacks: ["monospace"], weights: [400, 700], styles: ["normal", "italic"], formats: ["woff", "ttf"], }, ], });

仓库默认配置 astro.config.ts 使用的字体族是Google Sans Code，字重为[300, 400, 500, 600, 700]、样式含normal与italic、格式含woff与ttf，并绑定cssVariable: "--font-google-sans-code"。而两个 OG 生成端点正是通过该 CSS 变量名从fontData中取字体（fontData["--font-google-sans-code"]），因此：

如果修改了cssVariable，必须同步更新两个文件中的对应 key：

• src/pages/og.png.ts
• src/pages/posts/[...slug]/index.png.ts

字重匹配的底层实现在 src/utils/getFontPathByWeight.ts：它从FontData[]中按weight === String(weight)与style === "normal"（默认）筛选，再取src中format === "truetype"（默认，即 ttf）的文件 URL；若同时存在 woff 与 ttf 两种格式，该函数默认优先取 ttf 供 Satori 使用。两个端点中，若 400 或 700 字重的字体路径任一缺失，会直接抛出"Cannot find the font path."错误——这也解释了为何官方强调必须同时提供两种字重。

权衡：构建时间与性能

动态 OG 图片虽然方便，但并非没有代价：AstroPaper 会在构建期为每一篇符合条件的文章生成一张 PNG（即 frontmatter 未指定 ogImage 且非 draft 的文章），因此总构建时间会随内容量增长。

好消息是，AstroPaper v6 中 OG 图片生成性能相比早期实现已有显著提升（对应 PR #632 的优化），单张图片的额外开销在实战中已低很多。如果站点内容量极大、仍希望进一步压缩构建时间，可以在 astro-paper.config.ts 中显式关闭该功能：

features: { // ... dynamicOgImage: false, // 关闭后需要为文章逐个提供 ogImage }

关闭后会发生两件事，均可从源码得到印证：

1. index.png.ts的getStaticPaths()直接返回[]，不再为任何文章生成动态图；其GET处理器也会返回 404（src/pages/posts/[...slug]/index.png.ts）。
2. resolveDefaultOgImagePath（src/utils/resolveDefaultOgImagePath.ts）进入"强制静态"分支：public/{site.ogImage}文件必须存在，否则构建直接失败。因此关闭功能前，请确认public/下确实存在site.ogImage指定的图片（仓库默认为 public/default-og.jpg），并为重要文章在 frontmatter 中逐个配置ogImage。

已知限制

截至文档撰写时，Satori 仍是一个较新、尚未发布 major 正式版的库，因此动态 OG 图片功能也存在一些限制：

• RTL（从右到左）语言暂不支持：Satori 的排版引擎尚未覆盖希伯来语、阿拉伯语等 RTL 文本的布局需求，此类站点的 OG 图呈现效果无法保证。
• 标题中的 emoji 渲染可能比较棘手：Satori 对 emoji 采用单独的渲染机制（文档示例见 Satori 官方 README 的 Emojis 一节），直接放入标题可能出现缺字或布局异常，建议在生成图前对标题做规避处理（如替换或移除 emoji）。

小结

AstroPaper 的动态 OG 图片功能，用一条"frontmatter 无 ogImage + 非 draft → 构建期自动生成 PNG"的规则，把社交分享图的维护成本降到了最低：作者零配置即可让每篇文章拥有包含标题、作者、站点名的专属预览图。v6 版本通过复用 Astro Fonts 字体管线和experimental_getFontFileURL()解决了非拉丁字符缺字问题（前提是字体族覆盖你的语言，且同时声明 400/700 字重并同步cssVariable），同时以features.dynamicOgImage开关为超大站点保留了控制构建开销的余地。理解这些实现细节后，你便可以在自己的 AstroPaper 站点上放心启用动态 OG 图片，并针对目标受众的语言与构建规模做最合适的配置。

• 前端