从 Hugo 和 Next.js 回到 Astro 7：一次博客重构复盘

为什么又一次重构博客#

这个博客前后换过几套方案：最早用 Next.js 搭过完整的 React 应用，后来为了减少维护成本迁到 Hugo，到了 2026 年又重新回到 Astro。

这次回到 Astro，并不是因为 Hugo 不好，而是因为当前需求变得更具体了：

文章数量和标签数量都很多，需要更稳定的内容组织和搜索
希望保留静态站点的部署方式，不引入数据库和长期运行的后端
需要在同一套站点里同时放文章、归档、标签、RSS、搜索和分享海报
希望页面结构、组件和样式都能直接维护，而不是被主题配置限制

Astro 的静态输出正好适合这个场景。文章在构建时生成 HTML，浏览器只加载需要的脚本，部署仍然是一份纯静态文件。

从模板到可维护的博客#

一开始使用的是 Firefly 主题，功能很齐全，但也带来了大量模板配置。真正开始写作后，问题逐渐集中在三件事：

页面里有很多主题自带的功能和默认文案
框架版本已经落后，部分依赖出现了兼容问题
移动端功能太多，页面虽然有动画，但滚动和点击体验不够轻

这次没有继续堆功能，而是先把项目整理成一个可以长期写作的基础工程。

Astro 7 升级踩到的坑#

从 Astro 6 升到 Astro 7 后，最大的变化不是页面组件，而是 Markdown 处理流程。

这个博客依赖大量 remark 和 rehype 插件，包括数学公式、代码块、Mermaid、PlantUML、Callout、外链处理和标题锚点。Astro 7 默认使用新的 Markdown 处理器后，原来的插件配置需要迁移到 @astrojs/markdown-remark 的 unified() 中。

同时还需要处理：

TypeScript 6 对脚本上下文和模块声明的更严格检查
Astro 7 不再接受旧的实验性配置
部分图标依赖在升级后需要改为内联 SVG
Astro 图标、Svelte、Tailwind 和 Expressive Code 的版本需要同步

这类升级最重要的不是“升到最新”，而是升级后文章内容仍然能正常渲染。构建检查通过之后，我又逐项检查了标题、代码块、数学公式、RSS 和搜索索引。

手机端性能优化#

这次重构最明显的变化来自移动端。

优化前，首页 Lighthouse 性能约 81，文章页约 74。页面本身不算特别重，但有几个问题叠在一起：

侧栏一次性渲染了 960 个标签
手机同时下载了桌面和手机两张背景图
头像和 favicon 都是 253 KB 左右的大 PNG
手机导航栏持续使用毛玻璃模糊
页面入场动画和大量阴影增加了绘制负担

调整后，侧栏只显示常用的 60 个标签，完整标签放到独立页面；背景图改成按屏幕加载；头像和 favicon 换成响应式 WebP；手机端关闭了不必要的模糊和入场动画。

本地移动端测试结果约为：

首页性能：81 → 94
文章页性能：74 → 98
首页下载量：约 1 MB → 337 KB
文章页下载量：约 1.1 MB → 398 KB

性能优化不是把所有效果都删掉，而是把“桌面端效果”和“手机端必要效果”分开。

图片和小图标也要工程化#

以前的头像和 favicon 直接使用一张 512×512 的大图。浏览器在导航栏里只显示几十像素，却要下载完整的 PNG，这是很典型的资源浪费。

现在的做法是：

头像由 Astro 生成多尺寸响应式图片
博客背景图区分桌面横图和手机竖图
手机背景提供多个宽度，让浏览器按 DPR 选择
favicon 使用圆形透明图标，并减少文件尺寸

图片优化看起来是小事，但对移动端首屏影响很大。

Swup 页面过渡留下的状态#

这次还定位了一个持续的导航问题：

手机端从首页进入归档后，再点击主页返回首页，页面结构回去了，但背景 Banner 仍然保持离开首页时的隐藏状态，需要刷新才能恢复。

原因是 Banner 容器没有参与 Swup 的内容替换，而离开首页时写入的内联 transform 和 opacity 一直保留着。修复方式是在页面内容替换完成后，如果当前已经回到首页，就主动清除旧的隐藏状态并恢复 Banner。

这个问题也说明，页面过渡库并不只是“加一个动画”。只要某些 DOM 被放在替换容器之外，就必须单独同步它的状态。

部署与最后的检查#

项目现在部署在 Vercel，使用 pnpm install --frozen-lockfile 安装依赖，构建时先跑 Astro 检查，再生成静态页面和 Pagefind 搜索索引。

最终验证包括：

Astro 和 TypeScript 检查无错误
Biome 格式检查通过
309 个页面成功构建
Pagefind 索引 271 个页面
站内链接检查没有发现坏链接
Vercel 自动部署完成，线上首页、文章页和标签页均可访问

总结#

这次重构的重点不是换一个框架，而是把博客从“能用的主题模板”整理成“可以持续写文章的基础设施”。

对个人博客来说，真正重要的不是功能最多，而是：

写作流程足够简单
页面在手机上足够稳定
内容能被搜索和归档
部署失败时能快速定位
以后再升级时，结构不会牵一发而动全身

Astro 7 现在承担的是这个基础角色。接下来更重要的，是把时间重新放回内容本身。