博客架构演进史：从 Hexo 到 Astro 的「无缝」肉身替换实录#

本文记录了我将个人博客从传统的 Hexo 框架彻底迁移至现代 Astro 框架的全过程。这不仅是一次技术的迭代，更是为了追求极致的开发体验与近乎完美的站点性能。

1. 迁移背景：#

旧博客基于 Hexo (Butterfly 主题)，采用 npm 安装模式。现在尝试无缝切去 Astro 继续折腾。

2. 核心迁移策略：原地替换，内容至上#

最稳妥的迁移方法是 「原地替换」 ，即在原有的 Git 目录下，清理 Hexo 引擎，注入 Astro 引擎，但必须 确保文章源码（Markdown）绝对安全 。

迁移前的目录结构 (Hexo npm 模式)#

1
GitBlog/
2
├── .git/                <-- 必须保留，连接远程仓库
3
├── node_modules/        <-- 需清理
4
├── source/              <-- 核心内容，需备份
5
│   └── _posts/          <-- 所有文章 (.md)
6
├── themes/              <-- 需清理
7
├── _config.yml          <-- 需清理
8
└── package.json         <-- 需清理

3. 实战演练：五步完成「换脑」手术#

Step 1: 备份文章源码 (资产保全)#

在进行任何删除操作前，先把文章拷贝到安全的地方：

1
# 假设你当前在父目录
2
mkdir -p ./temp_posts && cp -r ./GitBlog/source/_posts/* ./temp_posts/

Step 2: 清理旧引擎 (暴力拆解)#

进入项目目录，除了 .git 文件夹，清理其余所有 Hexo 相关文件：

1
cd ~/obsidian_vault/GitBlog
2
# 慎重：确保你已经完成了上一步的备份！
3
rm -rf source themes scaffolds _config.yml _config.butterfly.yml package.json package-lock.json node_modules db.json

Step 3: 初始化 Astro (旁路注入)#

由于 Astro 脚本默认不接受非空目录，我们需要先在一个临时文件夹里初始化，再搬运回来：

1
# 1. 回到父目录，在临时文件夹里初始化 Astro Blog 模板
2
cd ~/obsidian_vault
3
npm create astro@latest ./astro-temp -- --template blog --no-git --no-install
4

5
# 2. 将临时文件夹里的所有文件（包含隐藏文件）拷贝回 GitBlog
6
cp -r ./astro-temp/.* ./GitBlog/
7
cp -rn ./astro-temp/ ./GitBlog/
8

9
# 3. 删除临时文件夹
10
rm -rf ./astro-temp

Step 4: 适配 Front Matter & 搬回文章#

Astro 默认的文章路径在 src/content/blog/。

搬回文章：

1
mkdir -p GitBlog/src/content/blog/
2
mv ../temp_posts/* GitBlog/src/content/blog/

适配 Config (zod schema)： Hexo 的 date 格式和自定义字段（如 tags, categories, updated, abbrlink）会让 Astro 报错。你需要修改 src/content/config.ts 来兼容它们：

1
const blog = defineCollection({
2
  type: 'content',
3
  schema: z.object({
4
    title: z.string(),
5
    description: z.string().optional(),
6
    // 关键：将 Hexo 的日期字符串强制转换为 Date 对象
7
    pubDate: z.coerce.date(),
8
    updatedDate: z.coerce.date().optional(),
9
    heroImage: z.string().optional(),
10
    // 添加 Hexo 自定义字段
11
    tags: z.array(z.string()).optional(),
12
    categories: z.array(z.string()).optional(),
13
    abbrlink: z.string().optional(),
14
  }),
15
});

Step 5: 本地预览与验证#

1
cd GitBlog
2
npm install
3
npm run dev

访问 http://localhost:4321/，你会看到一个全新的、速度极快的 Astro 博客，而且你的旧文章都在！

4. 云端 CI/CD 换脑：GitHub Actions 适配#

由于引擎更换，原本的 deploy.yml 需要彻底重写。Astro 的编译产物在 dist/，我们需要用 npm run build 替换 hexo g。

全新的 .github/workflows/deploy.yml：

1
name: Astro Auto Deploy
2

3
on:
4
  push:
5
    branches:
6
      - main
7

8
env:
9
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
10

11
jobs:
12
  build:
13
    runs-on: ubuntu-latest
14
    steps:
15
      - name: Checkout source
16
        uses: actions/checkout@v4
17
        with:
18
          submodules: true
19

20
      - name: Setup Node.js
21
        uses: actions/setup-node@v4
22
        with:
23
          node-version: '24'
24
          cache: 'npm'
25

26
      - name: Install & Build
27
        run: |
28
          npm install
29
          npm run build
30

31
      - name: Configure SSH
32
        env:
33
          SSH_ID_RSA: ${{ secrets.HEXO_DEPLOY_PRI }}
34
        run: |
35
          mkdir -p ~/.ssh/
36
          echo "$SSH_ID_RSA" > ~/.ssh/id_rsa
37
          chmod 600 ~/.ssh/id_rsa
38
          ssh-keyscan github.com >> ~/.ssh/known_hosts
39

40
      - name: Deploy to Private Static Repo
41
        run: |
42
          # 进入 Astro 的构建产物目录
43
          cd dist
44
          # 初始化临时 Git 环境并推送到静态私有仓库
45
          git init
46
          git config --global user.name "your_username"
47
          git config --global user.email "your_email@example.com"
48
          git remote add origin git@github.com:yourname/yourname.github.io.git
49
          git checkout -b main
50
          git add .
51
          git commit -m "Rendered by Astro"
52
          # 强制覆盖，确保结构纯净
53
          git push -f origin main

注意： Cloudflare Pages 无需做任何修改。它只管监听静态仓库 yourname.github.io，无论是 Hexo 推送的 public 还是 Astro 推送的 dist，对于 Cloudflare 来说，它只看 .html 文件。

5. 扫尾工作：仓库改名与 Obsidian 优化#

为了更清晰地表达，我将远程源码仓库改名为 static-blog-source。

5.1 本地与 Submodule 同步#

1
# 1. 更新本地 Git 远程地址
2
cd GitBlog
3
git remote set-url origin git@github.com:yourname/static-blog-source.git
4

5
# 2. 回到父目录 (Obsidian 主库)，同步子模块路径
6
cd ..
7
# 慎重：确保你已经在 GitHub 网页端完成了改名操作
8
git submodule sync

5.2 Obsidian 侧边栏正则过滤 (File Explorer++)#

由于 Astro 的目录结构复杂，我们需要更新正则过滤，让侧边栏只显示文章目录： Hide Filter:

1
^GitBlog/(?!(src/|src$)).*|^GitBlog/src/(?!(content/|content$)).*|^GitBlog/src/content/(?!(blog/|blog$)).*

6. 总结#

成功