作为一个刚从 Windows 阵营转战 MacOS 的新手，我在迁移 Hexo 博客时着实踩了不少坑。尤其是环境搭建阶段，习惯了 Windows 下 “下一步到底” 式的安装，在 Mac 上遭遇了第一个下马威。

一、环境搭建

作为一个刚从 Windows 阵营转战 MacOS 的新手，我在迁移 Hexo 博客时着实踩了不少坑。尤其是环境搭建阶段，习惯了 Windows 下 “下一步到底” 式的安装，在 Mac 上遭遇了第一个下马威。

1.1 安装 Git 与 Node.js

起初没仔细看 Hexo 官方文档，直接从 Git 和 Node.js 官网下载了安装包进行安装。过程倒是顺利，和 Windows 一样傻瓜式点击下一步就完成了。然而当我在终端输入命令安装 Hexo 时：

npm install -g hexo-cli

控制台瞬间弹出一大串红色报错信息：

npm WARN checkPermissions Missing write access to /usr/local/lib/node_modulesnpm ERR! code EACCESnpm ERR! syscall accessnpm ERR! path /usr/local/lib/node_modules...npm ERR! It is likely you do not have the permissions to access this file as the current user

1.2 EACCES 权限错误解析

仔细研究错误信息后发现，这是 MacOS 系统的权限管理机制在 “作祟”。默认情况下，/usr/local 目录受系统保护，普通用户没有写入权限。而 npm 全局安装包时默认会将文件写入该目录，这就导致了权限冲突。

1.3 解决方法探索

查阅 Hexo 官方文档后得知，使用 Homebrew 等包管理工具安装 Node.js 可以避免此类问题。不过文档也提供了两种解决 npm 权限问题的方案：

方案一：使用节点版本管理器重新安装 npm（推荐）

这种方法需要使用 nvm (Node Version Manager) 来管理 Node.js 和 npm 的安装，能彻底避免权限问题。但考虑到我已经安装了 Node.js，就选择了另一种更简便的方案。

方案二：手动更改 npm 的默认目录

这种方法通过修改 npm 的全局安装路径，将其指向用户有完全权限的目录：

# 1. 创建自定义npm全局安装目录mkdir ~/.npm-global# 2. 配置npm使用新路径npm config set prefix '~/.npm-global'# 3. 更新环境变量echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # 如果你使用的是zshsource ~/.zshrc

这里需要注意的是，不同的 shell 配置文件可能不同：

  • 使用 Bash 的用户应修改~/.bash_profile

  • 使用 Zsh 的用户应修改~/.zshrc（MacOS Catalina 及以后默认使用 Zsh）

1.4 验证安装结果

完成上述配置后，再次尝试安装 Hexo：

npm install -g hexo-cli

这次终于顺利通过，输入hexo -v可以看到已安装的 Hexo 版本信息。

1.5 最佳实践建议

虽然手动修改 npm 路径解决了问题，但从长期来看，使用包管理器安装 Node.js 仍是更优选择：

# 使用Homebrew安装Node.jsbrew install node

使用 Homebrew 安装的软件会被放置在用户有权限的目录，彻底避免权限问题。同时，Homebrew 还能方便地管理软件版本和依赖关系。

1.6 其他潜在问题

在环境搭建过程中，还可能遇到以下问题：

Node.js 版本不兼容

Hexo 对 Node.js 版本有一定要求，建议安装 LTS 版本。可以使用 nvm 轻松切换 Node.js 版本：

# 安装nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash# 使用nvm安装Node.js LTS版本nvm install --lts

终端配置问题

MacOS 默认的终端应用功能有限，推荐安装 iTerm2 并配置 Oh My Zsh，能极大提升开发体验：

# 安装iTerm2brew install --cask iterm2# 安装Oh My Zshsh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

二、博客文件迁移

环境搭建完成后，接下来就是将 Windows 上的博客文件迁移到 MacOS。这一步相对简单，但有几个细节需要注意。

2.1 备份原博客文件

首先需要从 Windows 系统中导出 Hexo 博客文件。主要需要备份以下内容：

  • 博客源文件目录（通常是你创建的 Hexo 项目目录）

  • 主题配置文件（如果有自定义修改）

  • 文章 Markdown 文件

  • 图片等静态资源

可以将这些文件复制到外部存储设备或通过云盘同步到 Mac。

2.2 克隆博客仓库

如果你之前使用 Git 管理博客源码，可以直接在 Mac 上克隆仓库：

git clone <你的博客仓库地址>cd <博客目录>npm install  # 安装依赖包

2.3 配置 SSH 密钥（如果需要）

如果需要将博客部署到 GitHub 等平台，需要配置 SSH 密钥：

# 生成SSH密钥ssh-keygen -t rsa -b 4096 -C "your_email@example.com"# 将公钥添加到GitHub/Gitee等平台pbcopy < ~/.ssh/id_rsa.pub

2.4 验证博客运行

在 Mac 上启动 Hexo 服务器，验证博客是否能正常运行：

hexo clean  # 清理缓存hexo g      # 生成静态文件hexo s      # 启动本地服务器

在浏览器中访问http://localhost:4000，应该能看到熟悉的博客界面。

三、主题与插件配置

迁移过程中，主题和插件的配置可能会出现问题，需要特别注意。

3.1 主题配置

如果使用的是第三方主题，需要重新安装：

cd <博客目录>git clone <主题仓库地址> themes/<主题名称>

然后将原主题的配置文件复制到新主题目录。

3.2 插件安装

检查原博客的package.json文件，安装缺失的插件：

npm install <插件名称> --save

3.3 常见插件问题

  • hexo-deployer-git：用于将博客部署到 GitHub，需要重新配置

  • hexo-renderer-pug 和 hexo-renderer-stylus：如果主题使用了 Pug 或 Stylus，需要安装相应渲染器

  • hexo-generator-search：搜索功能插件，可能需要重新生成索引

四、部署配置

最后一步是配置博客部署，确保能正常发布到线上。

4.1 GitHub Pages 部署

如果使用 GitHub Pages，需要修改_config.yml中的 deploy 配置：

deploy:  type: git  repo: git@github.com:yourusername/yourusername.github.io.git  branch: master

然后执行部署命令：

hexo clean && hexo g && hexo d

4.2 自定义域名配置

如果使用了自定义域名，需要在博客根目录下创建source/CNAME文件，内容为你的域名。

4.3 其他部署方式

如果使用其他平台（如 Gitee、Netlify 等），需要根据相应平台的要求进行配置。

五、总结

通过以上步骤，我成功地将 Hexo 博客从 Windows 迁移到了 MacOS。虽然在环境搭建阶段遇到了权限问题，但通过修改 npm 配置路径顺利解决。整个迁移过程需要注意文件备份、环境配置和部署设置等方面的细节。

5.1 迁移经验总结

  • 推荐使用包管理器：Homebrew 等包管理器能避免很多权限问题

  • 版本一致性：确保 Node.js 和 npm 版本与原环境一致

  • 配置文件备份：主题和插件配置文件要完整备份

  • 分步验证：每完成一步都进行验证，避免问题积累

5.2 MacOS 使用小贴士

  • 熟悉常用终端命令，提高开发效率

  • 配置 iTerm2 和 Oh My Zsh，提升终端体验

  • 了解 MacOS 的文件权限管理机制

  • 善用 Homebrew 管理软件包

通过这次迁移，我不仅成功将博客迁移到了新系统，还对 Hexo 和 MacOS 的开发环境有了更深入的了解。希望这篇文章能帮助其他从 Windows 迁移到 MacOS 的 Hexo 用户少走弯路。