博客迁移全记录：从 Hexo 到 Astro 的完整操作复盘

这篇文章完整记录了本站从 Hexo（Solitude 主题）迁移到 Astro（vhAstro-Theme + macOS 风格定制）的过程：环境准备、文章与封面迁移、构建验证、GitHub 链接替换，每一步都附了具体命令。

背景

旧博客跑在 Hexo 上，主题是 Solitude，38 篇文章存在 source/_posts/ 下。新项目 AstroLog 基于 vhAstro-Theme（Astro 5），做了 macOS 风格定制：菜单栏红绿灯、实时时钟、磨砂玻璃卡片、底部 Dock。

迁移目标：把 38 篇文章和全部封面图从 Hexo 搬进 Astro 项目，保持链接稳定、构建零错误。

第一步：环境准备

新机器上缺两样东西：Git 和 pnpm。

1. 安装 Git

机器上没有 winget / choco / scoop，直接从 GitHub 官方 Release 下载安装包静默安装：

# 下载 Git for Windows 最新版（2.55.0.5，约 62MB）
Invoke-WebRequest -Uri "https://github.com/git-for-windows/git/releases/download/v2.55.0.windows.5/Git-2.55.0.5-64-bit.exe" -OutFile "$env:TEMP\Git.exe"

# 静默安装（Inno Setup 参数）
Start-Process "$env:TEMP\Git.exe" -ArgumentList '/VERYSILENT','/NORESTART','/SP-','/SUPPRESSMSGBOXES' -Wait -PassThru

# 验证（新开的终端才能识别新 PATH）
git --version   # git version 2.55.0.windows.5

2. 启用 pnpm

Node 自带 corepack，但 pnpm 命令本身不在 PATH 里：

corepack enable   # 在 Node.js 目录生成 pnpm/yarn 的启动器

# 如果 PowerShell 报"禁止运行脚本"，需要放开当前用户执行策略：
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

pnpm --version    # 11.24.0

⚠️ PATH 和执行策略改完后，要新开一个终端窗口才会生效。

3. 修复依赖

克隆下来的项目 node_modules 符号链接损坏（astro 找不到 kleur，典型的 pnpm 安装不完整症状），重新安装即可：

pnpm install

pnpm 11 的目录布局和以前不同：顶层 node_modules/astro 是指向 .pnpm/astro@5.13.10_.../ 的符号链接，依赖统一 hoist 到 node_modules/.pnpm/node_modules/ 下——排查问题时别在旧位置找依赖。

第二步：文章与封面迁移

写了一个迁移脚本 script/migrate-hexo.js（--analyze 预览 / --run 执行），核心是 front-matter 转换：

Hexo 字段	Astro 字段	处理方式
`abbrlink`	`id`	直接复用，文章链接不变（`/article/{id}`）；为 `'0'` 时回退为标题 slug
`categories`（列表，层级）	`categories`（字符串）	取叶子分类（`教程/Git` → `Git`）
`sticky: N`	`top: true`	置顶文章
`updated`	`updated`	保留
`cover: /img/covers/xx.png`	`cover: /assets/images/hexo/...`	路径重写
`comments: false`	`comment: false`	保留关闭评论意图
`top_img` / `layout` / `swiper_index` 等	—	删除（主题用不到）

正文处理：

/img/... 和相对路径图片 → /assets/images/hexo/...（跳过代码块，避免误改语法示例）
Typora 式图片（image-1.png 直接放在 _posts/ 里）→ 移到 public/assets/images/hexo/posts/ 并重写引用
 摘要标记 → 清理（Astro 主题用 getDescription 自动截取摘要）

图片资源整体复制，90 个文件共 10.1MB：

node script/migrate-hexo.js --analyze   # 先看转换结果
node script/migrate-hexo.js --run       # 执行迁移

第三步：构建验证

pnpm build

结果：

✅ 205 个页面（38 篇迁移文章 + 8 篇原有文章 + 分类/标签/归档等），构建 12s 无错误
✅ 封面无缺失，dist/assets/images/hexo/ 完整
✅ RSS 46 条、Sitemap 176 个 URL、搜索索引 46 条
✅ 中文路径（英特尔CPU全系列解析/cpu.png）在 HTML 里被 URL 编码，浏览器自动解码，正常显示

第四步：GitHub 链接替换

把博客里代表”站主”的 GitHub 链接统一改成 https://github.com/nan-yy：

底部 Dock 的 GitHub 社交图标（原来是模板占位符）
侧边栏个人网站新增 GitHub 图标入口
关于页「联系我」
控制台水印（作者署名 + GitHub）
迁移文章里旧账号 SEYYl 的仓库链接（hexo_blog-source、hexo_blog、Markdownify）

保留了 Footer 的 “Powered by vhAstro-Theme”（主题署名）和文章里的第三方项目链接。

小结

链接稳定性：abbrlink 复用为 Astro 的 id，老链接不会断
脚本可复用：script/migrate-hexo.js 留着，以后加文章再迁移随时能跑
踩坑记录：pnpm 符号链接损坏要 pnpm install 重装；corepack 启用的 pnpm 受 PowerShell 执行策略限制；SVG 封面用 sharp 渲染要验证中文字体
小发现：Desktop\AstroLog 其实是指向 nanyu-blog 的目录联接（Junction），两边路径操作的是同一份文件

迁移完成后的博客跑在 Astro 5 上，构建 205 页 12 秒，文章、封面、链接全部就位。

南与

背景