这篇文章是一次完整复盘，记录我如何把个人博客从「刚初始化模板」做到「真正可用、可持续更新」。

1. 起点：先把站搭起来

这次我选择了 Astro 作为博客框架，原因很直接：

• 静态输出友好，天然适合 GitHub Pages。
• 内容写作体验简单，Markdown 成本低。
• 后续扩展（i18n、搜索、评论、SEO）路径清晰。

项目一开始就定了一个约束：所有构建产物都在当前路径内管理，包括 npm cache，方便本地可控和排查。

2. 功能迭代：从能跑到能用

在基础模板跑通后，我按优先级补齐了核心能力：

• 多语言（zh-cn + en）
• 动效与主题切换
• 目录（TOC）与阅读时长
• Pagefind 搜索
• Giscus 评论
• JSON-LD 与基础 SEO

这一步的关键不是“功能数量”，而是每加一项都保持静态部署兼容。

3. 关键故障一：页面能打开，但 About / Search / Blog 点进去 404

这是最影响体验的问题。

根因是：站点部署在 GitHub Pages 项目路径下（/my-astro-blog/），但很多内部链接写成了根路径（如 /about、/search、/blog）。

修复思路：

1. 所有内部跳转统一走 base-aware 路径。
2. i18n 链接生成逻辑加上 import.meta.env.BASE_URL。
3. 搜索和静态资源路径也统一按 base 拼接。

修完后，导航、首页入口、语言切换都恢复正常。

4. 关键故障二：评论框有时不出现

这个问题更隐蔽：首屏有时正常，但站内跳转后评论框消失。

根因是站点启用了 ClientRouter，页面切换是客户端 swap，第三方脚本不能只在首次加载时初始化。

修复策略：

• 在 astro:page-load 生命周期里重新初始化 Giscus。
• 做幂等保护，避免重复注入 iframe。
• 用路径变化做重挂载判定。
• 语言值从 zh-cn 映射到 Giscus 需要的 zh-CN。

最后一次排查发现，代码没问题后仍报 “giscus is not installed on this repository”，这个属于仓库配置问题。安装并授权 Giscus App 后，评论功能恢复正常。

5. 关键故障三：部署成功但仍有 Node20 deprecation 警告

我把 workflow 里可控的 action 都升级到了新版（checkout@v6、setup-node@v6、upload-pages-artifact@v4），也尝试了 Node24 强制环境变量。

结论是：剩余警告来自上游 action 的内部依赖，当前仓库层面已经做到可控上限，需要等待官方版本进一步更新。

6. 这次项目最重要的收获

对我来说，这次不只是“做了一个博客”，而是形成了一条可复用的上线路径：

• 先明确部署模型（项目子路径 vs 根域名）。
• 所有链接从第一天就按 base 设计。
• 第三方脚本默认按客户端路由场景验证。
• 每次修复都做构建验证 + 线上验证。

7. 接下来我会怎么继续

接下来会持续做两件事：

1. 保持稳定发文，把这个博客真正变成长期输出阵地。
2. 继续做工程化打磨（监控检查清单、自动化验证、内容质量提升）。

如果你也在做个人博客，我最想给的一条建议是：

先把“可持续发布链路”打通，再追求花哨功能。

这样你会更快从“搭站”走到“长期写作”。