前言

最近开始捣鼓 Hexo，一个轻量的静态博客框架，主要是想找个地方安静地记录点东西，也顺便体验下 Hexo + Git 的完整部署流程。虽然官方文档写得已经够详细了，但在 Mac 上操作的过程中还是踩了不少小坑，于是就决定把整个过程整理记录下来，也方便自己回顾。

准备工作

安装 Homebrew

Homebrew 是 macOS 下最常用的包管理工具，后续需要用它来安装依赖。使用以下命令进行安装：

1
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后可以运行 brew -v 检查是否安装成功。

安装 Git 和 Node.js

Git 是 Hexo 项目版本控制的基础，而 Hexo 则基于 Node.js 运行。macOS 自带 Git，如果你希望使用最新版本，也可以通过 Homebrew 升级。确认 Git 安装：

1
git --version

然后安装 Node.js（包含 npm）：

1
brew install node

安装 Hexo 并初始化项目

使用 npm 全局安装 Hexo CLI 工具：

1
npm install -g hexo-cli

安装完成后，在你希望存放博客的路径下初始化项目：

1
2
3
hexo init blog
cd blog
npm install

这里的 blog 是你博客项目的文件夹名，可以根据喜好替换。

⚠️注意：以下所有的hexo命令都需要在blog路径下执行，即确保先执行cd blog。

初始化后可以生成和本地预览博客：

1
2
hexo generate 或 hexo g   # 生成静态文件
hexo server 或 hexo s     # 启动本地服务器

然后访问浏览器中的 http://localhost:4000 即可看到博客初始页面。

部署到 GitHub Pages

Hexo 默认使用 public 文件夹存放生成的静态资源，我们只需要把它部署到 GitHub 即可上线。

配置 GitHub SSH 密钥

如果你还未在本机配置过 SSH，可以按以下步骤进行：

1
ssh-keygen -t ed25519 -C "[email protected]"

一路回车后，复制生成的公钥内容：

1
pbcopy < ~/.ssh/id_ed25519.pub

然后前往 GitHub 个人设置中添加 SSH key。

设置 Git 账号

1
2
git config --global user.name "YourName"
git config --global user.email "[email protected]"

完成这些工作以后可以执行以下命令测试，出现你的Github用户名代表配置成功：

1
ssh [email protected]

安装部署插件

Hexo 需要用到一个插件将博客内容部署到 GitHub：

1
npm install hexo-deployer-git --save

创建 GitHub 仓库并启用 Pages

  1. 登录 GitHub，点击右上角“+” → “New repository”；
  2. 仓库名称建议为：yourusername.github.io（将 yourusername 替换为你的 GitHub 用户名）；
  3. 选择 public 类型，点击创建；
  4. 创建成功后进入仓库页面，点击“Settings” → 左侧“Pages”；
  5. 在“Source”处选择 Deploy from a branch；
  6. 选择 main 分支，文件夹选择 / (root)，点击保存；
  7. 页面会自动生成一个访问链接，等待几分钟后就能访问。

配置 Hexo 部署信息

修改blog目录下 _config.yml 配置文件，添加以下部署信息：

1
2
3
4
deploy:
  type: git
  repo: [email protected]:yourusername/yourusername.github.io.git
  branch: main

确保你的仓库已经创建完成且为 public，然后执行：

1
2
3
hexo clean
hexo g
hexo d

第一次部署可能会提示是否接受 SSH 密钥认证，输入 yes 即可。

自定义域名配置（可选）

如果你有自己的域名，可以将博客部署在个性化的地址。

  1. 在博客目录中创建一个 CNAME 文件：
1
echo "yourdomain.com" > blog/source/CNAME
  1. 在你的域名服务商（如 Cloudflare、阿里云等）中添加一条 CNAME 记录，指向 GitHub Pages：
1
yourusername.github.io

⚠️ 注意：如果你使用 Cloudflare，添加 CNAME 记录时请关闭“小云朵”图标（即不要开启代理），否则可能导致 GitHub Pages 无法正确解析。

  1. 登录 GitHub，进入你的博客仓库页面，点击“Settings” → 左侧“Pages”；

  2. 在“Custom domain”栏中填写你的域名 yourdomain.com 并点击“Save”；

  3. 勾选 Enforce HTTPS，等待 DNS 解析完成后访问你的自定义域名即可生效。

  4. 同时确保 _config.yml 中的 url 字段也已更新为你的域名：

1
url: https://yourdomain.com

这样每次部署时，Hexo 会自动将 CNAME 文件同步至 public 文件夹，实现自定义域名访问。

常用命令整理

⚠️注意：以下hexo命令均需要切换到blog文件夹执行，确保先执行cd blog

  • hexo clean：清理缓存文件（如生成失败时可用）
  • hexo new "post name" 或 hexo n "post name" ：创建新文章
  • hexo generate 或 hexo g：生成静态资源
  • hexo server 或 hexo s：本地预览网站
  • hexo deploy 或 hexo d：部署博客到远端

后记

整个过程看似步骤繁多，实际上操作几次就熟悉了。如果你也在寻找一个简洁、可控的写作平台，不妨试试 Hexo。接下来可以根据自己的喜好更换主题、美化样式，慢慢打造属于自己的博客空间。