Hexo 博客从 Windows 迁移到 Mac 完整指南

✨ 写在前面

最近将我的 Hexo 博客从 Windows 系统迁移到了 Mac 系统。虽然 Hexo 本身是跨平台的，但在迁移过程中还是遇到了一些需要注意的问题。本文详细记录了整个迁移过程，希望能帮助有相同需求的读者顺利完成迁移工作。

📋 迁移前准备

在开始迁移之前，建议先做好以下准备工作：

  1. 备份重要文件

    • 备份整个博客文件夹（包括 source/、themes/、_config.yml 等）
    • 确保所有博客文章和配置文件都已保存

  2. 检查系统环境

    • Mac 系统：macOS 15.5（或其他版本）
    • Node.js：建议使用 LTS 版本
    • npm：随 Node.js 一起安装

🚀 迁移步骤

1. 安装 Node.js 和 npm

Mac 系统上安装 Node.js 有多种方式，推荐使用 Homebrew：

1
2
3
4
5
6
# 使用 Homebrew 安装 Node.js（会自动安装 npm）
brew install node

# 验证安装
node --version
npm --version

或者从 Node.js 官网 下载安装包直接安装。

2. 重新安装项目依赖

重要提示：从 Windows 迁移到 Mac 时，必须删除旧的 node_modules 和 package-lock.json，然后重新安装依赖。这是因为：

  • 不同操作系统的二进制文件不兼容
  • 原生模块需要针对当前系统重新编译
1
2
3
4
5
6
7
8
# 进入博客目录
cd /path/to/your/blog

# 删除旧的依赖文件
rm -rf node_modules package-lock.json

# 重新安装依赖
npm install

安装完成后，你会看到类似以下的输出：

1
added 334 packages, and audited 335 packages in 1m

3. 验证 Hexo 安装

检查 Hexo 是否能正常工作：

1
2
# 检查 Hexo 版本
npx hexo version

如果看到 Hexo 的版本信息，说明安装成功。例如：

1
2
3
4
hexo: 7.3.0
hexo-cli: 4.3.2
os: darwin 24.5.0 15.5
node: 25.1.0

4. 测试博客生成功能

1
2
3
4
5
# 清理之前的生成文件
npx hexo clean

# 生成静态文件
npx hexo generate

如果生成成功，你会看到类似以下的输出：

1
2
3
4
5
INFO  Start processing
INFO  Generated: index.html
INFO  Generated: archives/index.html
...
INFO  343 files generated in 2.34 s

注意：生成过程中可能会出现一些 LaTeX 相关的警告，这些通常不影响博客的正常使用，可以忽略。

5. 检查 Git 和 SSH 配置

如果你的博客需要部署到 GitHub Pages，需要确保 Git 和 SSH 配置正确：

1
2
3
4
5
# 检查 Git 版本
git --version

# 测试 SSH 连接到 GitHub
ssh -T [email protected]

如果看到 Hi [你的用户名]! You've successfully authenticated...，说明 SSH 配置正确。

6. 测试本地预览

1
2
3
4
# 启动本地服务器
npx hexo server
# 或使用 npm 脚本
npm run server

然后在浏览器中访问 http://localhost:4000 查看博客效果。

⚙️ 常用命令

迁移完成后，你可以使用以下命令来管理博客：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 清理生成的文件
npm run clean
# 或
npx hexo clean

# 生成静态文件
npm run build
# 或
npx hexo generate

# 启动本地服务器预览
npm run server
# 或
npx hexo server

# 部署到 GitHub
npm run deploy
# 或
npx hexo deploy

⚠️ 常见问题

1. 权限问题

如果遇到权限相关的错误，可以尝试：

1
2
3
4
5
# 使用 sudo（不推荐，但有时需要）
sudo npm install

# 或者修复 npm 权限
sudo chown -R $(whoami) ~/.npm

2. 依赖安装失败

如果 npm install 失败，可以尝试：

1
2
3
4
5
6
7
8
# 清除 npm 缓存
npm cache clean --force

# 使用国内镜像源（如果网络较慢）
npm config set registry https://registry.npmmirror.com

# 重新安装
npm install

3. Git 仓库初始化

如果你的博客目录还没有初始化为 Git 仓库，可以：

1
2
3
4
5
# 初始化 Git 仓库
git init

# 添加远程仓库（根据你的配置修改）
git remote add origin [email protected]:你的用户名/你的仓库名.git

4. 安全警告

安装依赖时可能会看到一些安全警告：

1
11 moderate severity vulnerabilities

这些警告通常不影响使用，如果需要修复，可以运行：

1
npm audit fix

📝 迁移检查清单

完成迁移后，建议检查以下项目：

  • [ ] Node.js 和 npm 已正确安装
  • [ ] 项目依赖已重新安装
  • [ ] Hexo 命令可以正常执行
  • [ ] 博客可以正常生成（hexo generate）
  • [ ] 本地预览功能正常（hexo server）
  • [ ] Git 和 SSH 配置正确（如需要部署）
  • [ ] 所有博客文章和图片正常显示
  • [ ] 主题配置正常加载

🎉 迁移完成

完成以上步骤后，你的 Hexo 博客就已经成功从 Windows 迁移到 Mac 了！现在你可以：

  • 正常编写和发布博客文章
  • 使用本地预览功能查看效果
  • 部署到 GitHub Pages 或其他平台
  • 享受 Mac 系统带来的流畅体验

💡 总结

从 Windows 迁移到 Mac 的 Hexo 博客迁移过程相对简单，主要步骤包括：

  1. 重新安装依赖：删除旧的 node_modules 和 package-lock.json，重新运行 npm install
  2. 验证功能：测试 Hexo 的生成、预览等功能是否正常
  3. 检查配置：确保 Git、SSH 等配置正确

整个过程大约需要 10-15 分钟，主要时间花在依赖安装上。如果遇到问题，可以参考本文的"常见问题"部分，或者查看 Hexo 官方文档。

希望这篇文章能帮助到有相同需求的读者！如果你在迁移过程中遇到其他问题，欢迎在评论区留言讨论。

📚 参考资源