环境准备

Node.js

推荐使用 nvs（Node Version Switcher）管理版本：

1
2
3
4
5
# 下载 nvs
git clone https://github.com/jasongin/nvs.git
cd nvs
./nvs.sh add lts
nvs use lts

或直接去 nodejs.org 下载 LTS 安装包。

1
2
3
4
5
6
# 使用 Homebrew
brew install node

# 验证
node -v
npm -v
1
2
3
4
5
6
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Fedora
sudo dnf install nodejs

Git

去 git-scm.com 下载安装包，一路下一步。
安装后右键菜单会出现 “Git Bash Here”。

1
brew install git
1
2
3
4
5
# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

安装 Hexo

1
2
3
4
5
6
7
8
# 替换 npm 源为国内镜像
npm config set registry https://registry.npmmirror.com

# 全局安装 hexo-cli
npm install hexo-cli -g

# 验证
hexo -v

初始化博客

1
2
3
4
5
6
7
8
9
10
11
12
# 新建博客文件夹（建议非系统盘）
mkdir D:/blog/superBrain
cd D:/blog/superBrain

# 初始化
hexo init

# 安装依赖
npm install

# 本地预览
hexo s

浏览器打开 http://localhost:4000 看到默认主题即成功。

部署到 GitHub

1. 新建仓库

仓库名必须是 用户名.github.io，例如 QINchao998314.github.io。

2. 配置 SSH 密钥

1
2
3
4
5
# 生成密钥
ssh-keygen -t ed25519 -C "你的邮箱"

# 查看公钥
cat ~/.ssh/id_ed25519.pub

复制公钥 → GitHub → Settings → SSH and GPG keys → New SSH key。

测试连接：

1
ssh -T git@github.com

3. 配置 Git 用户

1
2
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

4. 安装部署插件

1
npm install hexo-deployer-git --save

5. 修改 _config.yml

1
2
3
4
deploy:
  type: git
  repository: git@github.com:用户名/用户名.github.io.git
  branch: main

6. 部署命令

1
2
3
hexo clean    # 清理缓存
hexo g        # 生成静态文件
hexo d        # 部署到 GitHub

访问 https://用户名.github.io 即可。

常用命令速查

命令 作用
hexo new "文章标题" 新建文章
hexo new page "页面名" 新建独立页面
hexo g 生成静态文件
hexo s 本地预览
hexo d 部署
hexo clean 清理 public 和 cache

常见问题

Q: 4000 端口被占用？

1
hexo s -p 4001

Q: 部署后样式丢失？
检查 _config.yml 的 url 和 root 配置。

Q: 文章中文标题 URL 乱码？
安装 hexo-abbrlink 生成唯一链接，见 Butterfly 配置篇。