博客重构记录：从 Hexo 迁移到 Astro

#旧博客的问题

1. 技术栈老旧

   • Hexo 5.1.1（2020 年版本）
   • 构建速度慢
   • 开发体验一般
   • 缺少现代化特性

2. 维护困难

   • 5 年没更新，依赖版本过旧
   • 主题定制困难
   • 缺少搜索功能

3. 部署问题

   • GitHub Pages 国内访问慢
   • 没有 CDN 加速
   • 构建不稳定

#为什么选择 Astro？

1. 性能优秀

   • 零 JS 默认输出
   • 构建速度极快
   • 自动图片优化

2. 开发体验好

   • 支持 MDX
   • 组件化开发
   • TypeScript 支持
   • 热更新快

3. 生态丰富

   • 集成 React、Vue 等框架
   • 丰富的插件系统
   • 现代化的工具链

#1. 选择主题

选择了 sh-blog-next 主题，特点：

• 基于 Astro 6.0
• 支持 MDX
• 集成 Tailwind CSS 4
• 内置搜索功能
• 响应式设计

#2. 配置博客信息

修改 shblog.config.ts：

1
export const config: Config = {
2
  title: "阿兜哥爸爸的博客",
3
  description: "记录技术成长的点点滴滴",
4
  lang: "zh-CN",
5
  author: {
6
    name: "笨叔丶",
7
    bio: "一个热爱技术的开发者",
8
    // ... 其他配置
9
  }
10
}

#3. 迁移文章

1
---
2
title: 文章标题
3
date: 2020-09-04 11:08:11
4
tags:
5
  - Java
6
  - RPC
7
cover: https://example.com/image.jpg
8
---

1
---
2
title: 文章标题
3
description: 文章描述
4
pubDate: 2020-09-04T11:08:11.000Z
5
heroImage: https://example.com/image.jpg
6
category: ["技术实践"]
7
draft: false
8
tags:
9
  - Java
10
  - RPC
11
---

#4. 初始化 Git 仓库

1
cd blog-next
2
git init
3
git remote add origin https://github.com/adougebabi/adougebabi.github.io.git
4
git add .
5
git commit -m "feat: 重构博客到 Astro 框架"
6
git push -u origin main

#为什么选择 Cloudflare Pages？

1. 全球 CDN 加速 - 300+ 数据中心
2. 国内访问快 - 比 GitHub Pages 快 3-5 倍
3. 无限带宽 - 完全免费
4. 构建速度快 - 平均 1-2 分钟
5. 自动 HTTPS - 免费 SSL 证书

#部署步骤

1. 访问 Cloudflare Dashboard

2. 点击 Workers & Pages → Create application → Pages

3. 连接 GitHub 仓库

4. 配置构建设置：

   • Framework preset: Astro
   • Build command: pnpm build
   • Build output directory: dist
   • Root directory: /（留空）
   • Environment variables:
     • NODE_VERSION = 22
     • PNPM_VERSION = 10

5. 点击 Save and Deploy

#坑 1：pnpm 版本不兼容

问题：

1
ERR_PNPM_UNSUPPORTED_ENGINE
2
Expected version: >=10.0.0
3
Got: 9.10.0

原因： 主题要求 pnpm 10+，但 Cloudflare Pages 默认使用 9.10.0

解决： 降低 package.json 中的版本要求

1
{
2
  "engines": {
3
    "pnpm": ">=9.0.0"  // 原来是 >=10.0.0
4
  }
5
}

#坑 2：远程图片不允许

问题：

1
[ERROR] Remote image https://raw.giteeusercontent.com/... is not allowed

原因： Astro 默认不允许外部图片链接

解决： 在 astro.config.mjs 添加域名白名单

1
export default defineConfig({
2
  image: {
3
    domains: ["raw.giteeusercontent.com"],
4
  },
5
  // ...
6
})

#坑 3：heroImage 类型错误

问题：

1
[ERROR] Transform failed with 1 error

原因： heroImage 类型定义只接受本地图片，不接受字符串 URL

解决： 修改 src/content.config.ts

1
schema: ({ image }) =>
2
  z.object({
3
    // 支持本地图片或外部 URL
4
    heroImage: z.union([image(), z.string()]).optional(),
5
    // ...
6
  }),

#坑 4：Cloudflare Workers 模式错误

问题：

1
[ERROR] Unexpected token `.`. Expected ... , *,  (, [, :, , ?, = or an identifier

原因： 创建项目时选择了 Workers，自动添加了 @astrojs/cloudflare 适配器，但纯静态博客不需要

解决：

1. 删除项目重新创建
2. 选择 Pages（不是 Workers）
3. 不要设置 Deploy command
4. Cloudflare Pages 会自动部署 dist 目录

#坑 5：根目录配置错误

问题：

1
Failed: root directory not found

原因： 将 Root directory 设置成了 dist（输出目录）

解决：

• Root directory: /（项目根目录，留空）
• Build output directory: dist（构建输出目录）

#性能提升

• 构建时间：从 5 分钟降到 1.5 分钟
• 首屏加载：从 3s 降到 0.8s
• Lighthouse 评分：从 75 提升到 98

#功能增强

• ✅ 全文搜索（Pagefind）
• ✅ 响应式图片优化
• ✅ 代码高亮（Shiki）
• ✅ 数学公式支持（KaTeX）
• ✅ RSS 订阅
• ✅ Sitemap 自动生成

#访问速度

• 国内访问：从 5s 降到 1s
• 全球 CDN：自动分发到 300+ 节点
• HTTPS：自动配置，免费证书

#经验教训

1. 选对平台很重要 - Cloudflare Pages 比 GitHub Pages 更适合国内用户
2. 仔细阅读文档 - 很多坑都是配置不当导致的
3. 类型定义要准确 - TypeScript 的类型检查能避免很多问题
4. 环境变量要配对 - 本地和生产环境的差异要注意

#后续计划

• 添加评论系统（Giscus）
• 配置自定义域名
• 优化 SEO
• 添加更多文章
• 集成分析工具

#相关资源

• 新博客地址：https://blog.adoumi.site
• GitHub 仓库：https://github.com/adougebabi/adougebabi.github.io
• Astro 文档：https://docs.astro.build
• 主题仓库：https://github.com/510208/sh-blog-next