用 Astro+TS+Tailwind 构建支持静态搜索和动态 OG 图的 SEO 友好博客主题

方案简介

AstroPaper 是一个基于 Astro 的极简、响应式、无障碍且对 SEO 友好的博客主题模板。它面向希望快速搭建个人技术博客、文档站点或内容站点的开发者，作者按照自己的个人博客（satnaing.dev/blog）为参考设计与打磨。

仓库明确将它定位为「Astro blog theme」，并以 TypeScript 提供类型安全、TailwindCSS 负责样式，整体追求「super fast performance」与「accessible (Keyboard/VoiceOver)」。除博客核心能力外，还内置静态搜索、草稿、RSS、sitemap、MDX、可折叠目录以及动态 OG 图生成。

适合人群：

• 想用 Astro 框架搭个人博客但不想从零写 UI 的人；
• 重视 SEO、Lighthouse 分数、可访问性的内容创作者；
• 喜欢 Markdown/MDX 写作流，并希望类型安全的开发者。

使用与配置要点

常用命令

所有命令均在项目根目录的终端中执行：

| Command | Action |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| pnpm install | Installs dependencies |
| pnpm dev | Starts local dev server at localhost:4321 |
| pnpm build | Type-checks, builds the site, runs Pagefind indexing, and copies the index to public/pagefind/ |
| pnpm preview | Preview your build locally, before deploying |
| pnpm sync | Generates TypeScript types for all Astro modules |
| pnpm astro ... | Run CLI commands like astro add, astro check |

配置站点的 Google 验证

可在 astro-paper.config.ts 中设置 site.googleVerification 加入 Google 站点验证 HTML 标签：

export default defineAstroPaperConfig({
  site: {
    // ...
    googleVerification: "your-google-site-verification-value",

  // ...
});

文档入口

文档同时提供 markdown 与 blog post 两种形式：

• Configuration
• Add Posts
• Customize Color Schemes
• Predefined Color Schemes

可通过 README 的 Documentation 段链接到对应文章。

注意事项与常见问题

无障碍覆盖范围说明：作者在 Mac 上用 VoiceOver、在 Android 上用 TalkBack 测试了 AstroPaper 的屏幕阅读器可访问性，未能覆盖所有屏幕阅读器，但「accessibility enhancements in AstroPaper should be working fine on others as well」。

Pagefind 索引：搜索索引在构建时自动生成到 public/pagefind/，需要完整跑一遍 pnpm build 才能让搜索可用。

部署：默认推荐 Cloudflare Pages，可结合 pnpm preview 在部署前本地预览构建产物。

优缺点

• ✓ 静态站性能优异且 SEO 友好
• ✓ 类型安全 markdown 与高可定制
• ✕ 依赖 Pagefind 构建时索引
• ✕ 动态 OG 图依赖 Satori+Sha

出处

本方案挖掘自开源项目 satnaing/astro-paper，方案内容与实施命令均来自其 README 原文。