---
title: 网站迁移日志
abbrlink: 8f3b9d21
date: 2026-06-19 16:45:00
categories: 建站手札
tags:
  - 网站
  - Astro
  - 迁移
summary: 这篇文章记录一次个人网站迁移过程：为什么要从旧的博客构建流程迁到 Astro，迁移时处理了哪些内容、路由、评论、统计和搜索问题，以及这次折腾之后留下的一些经验。
---

这两天把网站又重新整理了一遍。

说是“迁移”，其实不只是换一个框架那么简单。真正花时间的地方，往往不是把页面跑起来，而是把原来那些散落在角落里的功能重新接好：文章路径、归档、分类、标签、评论、统计、搜索、友链、说说，还有一些以前顺手加上的小脚本。

这篇就当作一次迁移日志，记录一下为什么迁、怎么迁，以及迁完之后我对这个站点的新想法。

## 为什么要迁移

旧站点最开始更像是“能跑就行”的状态。文章能写，页面能生成，部署也能自动化，看起来已经够用了。

但用久之后，一些问题会慢慢冒出来：

- 主题改动越来越散，很多功能像补丁一样叠在一起。
- 想加一个小功能时，经常要先回忆以前改过哪里。
- 构建和部署流程虽然能用，但排查问题不够直观。
- 文章、组件、脚本之间的边界不清楚，维护起来有点累。

所以这次迁移的目标不是追新，而是把网站重新变成一个自己愿意继续维护的东西。

Astro 比较适合现在这个站点：内容以 Markdown 为主，页面大部分是静态的，但又需要少量动态能力，比如搜索、统计、评论和说说。它不会强迫整个网站都变成复杂的前端应用，刚好可以保留博客该有的轻量感。

## 迁移前的准备

动手之前，先把旧站点分成几类内容：

1. 文章内容：Markdown 文件、frontmatter、分类、标签、封面和摘要。
2. 页面结构：首页、归档、分类、标签、关于、友链、说说。
3. 站点功能：评论、统计、搜索、外链跳转、随机文章。
4. 构建部署：依赖安装、静态构建、生成 RSS 和站点地图。
5. 视觉细节：背景、图标、侧边栏、文章卡片、分页和版权信息。

这样做的好处是，迁移时不会被“整个网站”这四个字吓住。每次只处理一块，处理完就验证一块。

## 内容迁移

文章是整个迁移里最重要的部分。

我保留了按年份和月份整理文章的习惯，例如：

```txt
src/content/posts/2026/2026.6/
```

这样目录结构一眼就能看出文章的大致时间，也方便以后手动查找。

frontmatter 也尽量沿用原来的字段：

```yaml
title: 文章标题
abbrlink: 短链接
date: 2026-06-19 16:45:00
categories: 建站手札
tags:
  - 网站
  - Astro
summary: 文章摘要
```

其中 `abbrlink` 继续保留。旧文章已经被搜索引擎或其他页面引用过，链接最好不要随便变。为了避免以后手写遗漏，我也给构建流程加了自动补全短链的脚本，让没有 `abbrlink` 的文章在构建前自动生成一个。

## 页面重建

页面部分没有完全照搬旧主题，而是按现在的使用习惯重新拆了一遍。

首页负责展示最新文章和侧边栏信息；归档页负责按时间回看；分类和标签页负责内容整理；文章页则重点放在阅读体验上。

这次迁移里，我更想让每个页面都只做一件事：

- 首页：让访客快速看到最近更新。
- 归档：按时间浏览所有文章。
- 分类：按主题聚合内容。
- 标签：给文章提供更细的索引。
- 文章页：减少干扰，把正文、目录、版权和评论放在合适的位置。

以前有些功能会被塞到同一个地方，看起来热闹，但维护起来不舒服。现在拆开之后，结构清楚了很多。

## 搜索、评论和统计

博客不只是静态页面，还需要一些“活着”的功能。

搜索继续使用 Typesense。文章构建完成后，把标题、内容、分类、标签等信息推送到索引里，前端再通过搜索框查询。这样比纯前端全文搜索更轻，也更适合文章越来越多之后继续使用。

评论使用 Twikoo。评论系统不放在构建流程里，而是作为独立服务接入文章页。这样文章生成失败不会影响评论，评论服务维护也不会影响静态页面。

统计使用 Umami。站点里除了常规统计脚本，还单独做了一个 Worker 给侧边栏的信息卡提供访问量数据。前端不直接请求 Umami 后台接口，而是从 Worker 读取整理后的结果，顺手还能做一层缓存。

这些功能分开之后，网站本体仍然是静态站点，但又不会显得太“死”。

## 部署流程

迁移之后的构建流程变得更直白：

```bash
npm install
npm run build
```

`prebuild` 会先处理文章短链，然后 Astro 生成静态文件。生成结果放在 `dist` 目录里，后续只要把这个目录部署到静态托管环境即可。

比起以前围绕主题和生成器做很多定制，现在这个流程更接近普通前端项目。哪里出错、是哪一步出错，也更容易定位。

## 迁移中踩到的坑

最麻烦的是编码问题。

旧文章里有些内容在不同工具里显示不一致，终端、编辑器、构建器看到的结果可能不一样。最后只能统一按 UTF-8 来处理，新文章也尽量保持同一种编码，避免以后再次出现乱码。

第二个问题是路径。

迁移时如果只关心页面能不能打开，很容易忽略旧链接。尤其是文章页、RSS、归档和外链跳转这些地方，一旦路径变化太大，之前的收藏、搜索结果和站内链接都会受影响。所以短链和路由规则需要优先稳定下来。

第三个问题是“功能搬家”。

有些功能在旧站点里只是一个脚本，迁移时看起来复制过去就行。但真正接入时，还要考虑它依赖哪个 DOM、在哪个页面加载、有没有和 Astro 的静态渲染方式冲突。这个过程不能急，只能一个个验证。

## 迁移后的感受

这次迁移之后，网站变得更像一个可以长期维护的项目了。

文章归文章，组件归组件，配置归配置。想改导航，就去站点配置；想调文章卡片，就改对应组件；想加脚本，也能比较清楚地知道它应该放在哪里。

更重要的是，折腾网站这件事又变得有趣了一点。

以前加功能时，总有一种“别碰，能跑就行”的感觉。现在结构理顺之后，反而更愿意继续给它添东西：更好的搜索、更完整的站点信息卡、更舒服的阅读样式，或者干脆把一些旧文章重新整理一遍。

## 后续计划

迁移不是结束，只是把地基重新打了一遍。

后面大概还想继续做这些事：

- 整理旧文章，把明显过期或格式混乱的内容修一修。
- 给部分建站文章补充截图和最终效果。
- 优化搜索索引，让结果更准确。
- 给说说和友链页面补一点更自然的交互。
- 继续减少无用脚本，让页面加载更干净。

网站就是这样，永远都有能改的地方。

不过这次迁移至少让我重新确认了一件事：个人博客不一定要很复杂，但它最好是自己看着顺眼、改起来顺手、隔一段时间回来还愿意继续打理的地方。

这样就够了。
