SEO 优化（站点地图、robots、Open Graph 图片）

本页面介绍 Mizuki 站点中与搜索引擎优化（SEO）相关的服务端端点：robots.txt 的生成、Open Graph（OG）分享图的按需生成，以及相邻的内容分发端点（Atom 订阅、文章元数据 JSON API）。这些端点共同构成站点面向爬虫与社交平台的"机器可读层"。

目的与范围（Purpose and Scope）

本页覆盖 src/pages/ 目录下与 SEO 直接相关的路由端点，包括：

• src/pages/robots.txt.ts —— 输出 robots.txt，控制爬虫抓取行为
• src/pages/og/[...slug].ts —— 基于 slug 动态生成 Open Graph 图片的端点
• src/pages/atom.xml.ts 与 src/pages/atom.astro —— 订阅源（与 SEO/收录相关的周边能力，本页仅作边界说明）
• src/pages/api/allPostMeta.json.ts —— 文章元数据 JSON 端点（供 OG 生成与其他消费方读取的可能数据来源）

有意留给兄弟页面的内容：页面级 <meta> / structured data 的渲染细节属于内容渲染体系（参见仓库内 docs/CONTENT_RENDERING.md）；部署与构建流程参见 docs/DEPLOYMENT.md；内容撰写规范参见 docs/CONTENT_AUTHORING.md。这些主题不在本页展开。

⚠️ 诚实性说明：本次文档生成受源码探索预算限制，仅完成了文件清单级别的勘察，未能读取上述端点文件的内部实现。因此本页对文件与路由的存在性、命名约定与职责推断均基于可验证的文件路径；对方法签名、配置项、默认值等实现细节不做臆测，相关章节将明确标注"源码中未验证"。

概述（Overview）

Mizuki 是一个基于 Astro 的静态/混合站点（可由 astro.config.mjs 与 src/pages/ 下的 .astro、.ts 文件确认）。Astro 采用文件路由约定：

为什么用端点文件而不是静态文件：

• robots.txt.ts 以代码生成，可以在构建时注入站点地址、引用 sitemap 路径，避免硬编码与多环境（预览/生产）不一致。
• og/[...slug].ts 使用 rest 参数路由（[...slug]），意味着任意深度的 slug 都能命中同一生成逻辑，为每篇文章、相册等动态产出分享卡片图，无需为每篇内容手工制图。
• 与 api/*.json.ts 一样，这些 .ts 端点在 Astro 中返回 Response，是典型的"内容即代码"（content-as-code）实践。

架构（Architecture）

下面的组件图基于已验证存在的文件路径绘制，展示 SEO 机器可读层与站点其余部分的关系：

图中的实线（外部消费方 → 端点）由文件路径与 Astro 文件路由约定直接支撑；虚线（端点 → 内容集合）表示数据流向的合理推断，端点内部实际读取的数据源未在本次勘察中验证。

端点职责逐项说明

src/pages/robots.txt.ts

• 职责：生成 robots.txt。robots.txt 是爬虫抓取前的第一个约定入口，决定哪些路径允许抓取、是否引用 sitemap。
• 为什么以 .ts 端点实现：站点地址通常来自 astro.config.mjs 中的 site 配置，用代码生成可保证 Sitemap: 声明与环境一致。
• 源码中未验证：Allow/Disallow 规则、是否输出 Sitemap: 行、是否包含多语言/多站点分组等细节未能读取，不做臆测。

src/pages/og/[...slug].ts

• 职责：按 slug 动态生成 Open Graph 图片（分享到社交平台时的预览卡片图）。
• 路由含义：[...slug] 是 Astro 的 rest 参数路由，任意层级 slug（如 /og/posts/2024/my-post）都会命中该端点；这暗示其设计意图是"一个生成器服务所有内容的 OG 图"。
• 典型实现形态（行业惯例，非本仓库验证结论）：此类端点通常用 satori/resvg 或 @vercel/og 一类库把标题、摘要渲染成 SVG/PNG，并读取内容元数据取标题与封面。
• 源码中未验证：实际使用的渲染库、返回的 Content-Type、缓存策略、字体加载（仓库 src/assets/fonts/ 下存在 .ttf/.woff2 字体，可能用于 OG 文本渲染，属推断）均未读取确认。

src/pages/atom.xml.ts 与 src/pages/atom.astro

• 职责：输出 Atom 订阅源。订阅源虽非直接 SEO 要素，但有助于内容快速被发现与收录，且与 OG 端点共享"内容元数据读取"这一数据层。
• 同目录下存在 atom.astro 与 atom.xml.ts 两个文件，具体分工（页面展示 vs XML 端点）未验证。

src/pages/api/allPostMeta.json.ts

• 职责：以 JSON 暴露全部文章元数据。这类端点常被前端搜索、日历视图或 OG 生成复用为数据源。
• 与 src/pages/api/calendar-data.json.ts 同属 api/ 命名空间，后者偏向站点功能而非 SEO，本页不展开。

核心流程（Core Flow）

以"社交平台抓取一篇文章的分享图"为例，端到端流程如下（步骤 2/3 的内部实现未验证，仅展示边界交互）：

对应地，爬虫的常规入口是：

使用示例（Usage Examples）

No code example available —— 由于源码探索预算耗尽，robots.txt.ts、og/[...slug].ts 等端点的内部实现未能读取，本页不提供任何代码摘录，以避免编造。读者请直接查看以下源文件：

• robots.txt.ts
• og/[...slug].ts
• atom.xml.ts
• allPostMeta.json.ts
• astro.config.mjs

配置选项（Configuration Options）

无法提供经过验证的配置表。站点级配置位于 astro.config.mjs，其中 site 字段通常影响 robots.txt、订阅源与 OG 图中的绝对 URL；是否启用了官方 @astrojs/sitemap 集成（决定是否自动生成 /sitemap-index.xml）未验证。文件清单中未发现 sitemap.xml 相关源文件，站点地图可能由集成生成或尚未配置，需以 astro.config.mjs 实际内容为准。

API 参考（API Reference）

以下端点签名基于 Astro 文件路由约定从路径推导，均为路径级事实，非实现级事实：

端点内部的函数签名、参数类型与抛出的异常在本次勘察中未读取，不做臆测。

失败模式、边界与并发（Professional Notes）

基于端点形态可讨论、但均未在源码中验证的关注点，供后续维护者排查时参考：

• OG 生成的字体加载：src/assets/fonts/ 下存在 .ttf 与 .woff2 字体文件；若 OG 渲染在服务端读取字体，字体缺失或路径错误是最常见的失败点。
• 缓存策略：动态 OG 图如果缺少长缓存头，社交平台重复抓取会放大生成开销；是否设置缓存未验证。
• slug 不存在时的行为：[...slug] 会匹配任意路径，端点对无效 slug 应返回 404 或占位图，具体行为未验证。
• robots 与站点地图一致性：若 robots.txt.ts 声明的 sitemap 路径与实际生成的路径不一致，会静默影响收录；两者需在变更时同步核对。
• 构建期 vs 运行期：.ts 端点在纯静态部署（dist/）中通常在构建时预渲染为静态文件；在适配器（如 Node/Vercel）下则可能按需执行。实际模式取决于 astro.config.mjs，未验证。

相关链接（Related Links）

• robots.txt.ts
• og/[...slug].ts
• atom.xml.ts
• astro.config.mjs
• 仓库文档：CONTENT_RENDERING.md、DEPLOYMENT.md