个人博客上线前的收口记录

博客项目真正进入可长期使用的阶段，不是页面刚能打开的时候，而是那些容易被忽略的细节都被收拢起来：站点标题是否统一，GitHub 跳转是否正确，后台保存会不会写到正确仓库，搜索、RSS、Sitemap、favicon 和首页内容是否都指向同一个身份。

这篇记录不拆成很多小文章，只把上线前最重要的事情压成一份清单，方便以后迁移、复盘或继续迭代。

一、项目结构

当前博客以 Astro 为主体，页面、内容和组件分工比较清晰：

• src/pages/：页面入口，包括首页、文章列表、标签、归档、搜索、后台登录和 API。
• src/components/：复用组件，包括页头、页脚、文章卡片、标签、首页侧栏模块。
• src/layouts/：全站基础布局，负责 SEO meta、RSS 链接、favicon 和页面标题拼接。
• src/content/blog/：文章内容目录，使用 Markdown/MDX 管理。
• src/lib/：文章读取、排序、标签统计和后台认证辅助逻辑。
• public/：静态资源，包括 favicon、manifest 和后续图片资源。

这套结构的重点是保持内容和界面解耦。文章只关心 frontmatter 和正文，页面负责展示，组件负责复用样式。

二、站点身份配置

上线前最先要统一的是站点身份。标题、作者、描述、邮箱、GitHub 和域名应该有一个主入口，避免页面里到处写死。

项目里的主要配置集中在 src/consts.ts：

export const SITE = {
  title: "站点标题",
  description: "站点描述",
  author: "作者名",
  url: "站点域名",
  github: "GitHub 地址",
  email: "联系邮箱"
};

这些信息会影响页头、页脚、About 页面、RSS、社交分享和浏览器标题。改品牌名时，优先改这里，再检查有没有少量页面级硬编码残留。

三、浏览器与图标

public/favicon.svg 是浏览器标签页最直接的品牌信号。这个项目已经把原来的字母标识换成大写 H，保持和 Huhuya 的身份一致。

public/site.webmanifest 也需要同步维护：

• name：完整应用名。
• short_name：短名称。
• theme_color：移动端浏览器主题色。
• background_color：启动背景色。

这些不只是装饰，它们会影响移动端添加到桌面后的显示效果。

四、内容写作入口

文章内容放在 src/content/blog/，每篇文章最少需要包含这些字段：

---
title: "文章标题"
description: "文章摘要"
pubDate: 2026-06-09
tags: ["Tag"]
cover: "封面图地址"
---

文章适合记录三类内容：

• 项目建设：为什么这样设计结构、为什么选 Astro、部署链路如何决定。
• 使用方法：Git、Keystatic、Cloudflare、内容发布流程。
• 长期复盘：哪些功能真的有用，哪些只是搭建时看起来很美。

不要一开始就把所有主题拆成系列。个人博客早期更重要的是先把完整上下文写下来，再从真实使用中拆出值得扩写的文章。

五、Keystatic 与 GitHub

Keystatic 是内容后台。它的关键配置在 keystatic.config.ts：

storage: {
  kind: "github",
  repo: "owner/repo"
}

生产环境会使用 GitHub storage，后台保存文章时会直接提交到目标仓库，再触发 Cloudflare Pages 或 Workers 的重新部署。所以这里的仓库地址必须正确。

后台品牌名也在同一个文件里维护：

ui: {
  brand: {
    name: "后台显示名称"
  }
}

本地开发可以使用 local storage，避免每次测试内容都提交到远程仓库。

六、首页侧栏

首页侧栏承担的是“这个站点是谁在写”的第一印象。目前包含个人卡片、文章统计、随想便签和标签入口。

随想便签已经改成动态获取公开句子：页面加载后从一言接口请求三条内容，并按不同分类取值。为了避免三张便签出现同一句，会做去重重试；如果接口失败、超时或网络不可用，就保留本地备用文案。

这类外部内容适合做点缀，不适合成为页面核心。核心信息仍然应该由本地内容和站点配置兜底。

七、部署前检查

上线前建议按这个顺序检查：

1. astro.config.mjs 的 site 是否是真实域名。
2. src/consts.ts 的标题、描述、作者、GitHub、邮箱是否正确。
3. keystatic.config.ts 的 GitHub repo 是否指向目标仓库。
4. public/favicon.svg 和 site.webmanifest 是否和品牌一致。
5. README 中的仓库名、部署说明和环境变量说明是否同步。
6. 文章列表、标签、归档、搜索、RSS 是否能正常生成。
7. 后台登录密码和 Keystatic GitHub App 相关环境变量是否只放在环境配置里。

检查不是为了追求一次性完美，而是减少上线后那些“明明只是一个名字，却到处不一致”的小问题。

八、后续维护节奏

这个博客后续可以按轻量节奏维护：

• 新增文章时先写正文，再补标题、摘要、标签和封面。
• 改品牌信息时先改 src/consts.ts，再全局搜索旧名称。
• 改部署或后台配置时同步更新 README。
• 首页模块只保留真正有用的信息，少放无法长期维护的装饰。
• 每次上线前至少跑一次检查命令，并记录无法通过的原因。

博客不是一次搭完就结束的项目。它更像一个持续整理的工作台：结构负责稳定，内容负责生长，清单负责让自己下次回来时还能快速接上上下文。