用 Hexo + Anzhiyu 从零搭建个人博客（超详细步骤）

这篇文章把“Hexo + Anzhiyu 主题搭建并部署到 GitHub Pages”的流程写得尽可能详细，覆盖 Windows（PowerShell/Git Bash）和 macOS/Linux 常用命令、每条命令的目的、可能遇到的错误和解决办法、覆盖配置的原理与注意事项，以及部署后检查项。把此文件放到你的 Hexo 项目：source/_posts/ 下即可作为你的第一篇博客。

目录

  • 一、前提和准备
  • 二、创建/进入博客项目
  • 三、安装并应用 Anzhiyu 主题（推荐 git clone）
  • 四、安装渲染器（pug / stylus）
  • 五、覆盖主题配置（详解）
  • 六、本地生成与调试（含 debug）
  • 七、SSH 配置与验证（用于部署）
  • 八、自动部署（hexo-deployer-git）
  • 九、手动部署（public 目录方式）
  • 十、常见问题与排错（详尽）
  • 十一、建议的 _config.anzhiyu.yml 示例
  • 十二、自动化脚本（建议）
  • 十三、部署后检查清单

■ 一、前提和准备

你需要：

  • GitHub 帐户（已登录并可创建仓库）
  • Node.js（建议 LTS：14/16/18/20 均可；Node 24 也支持，但部分 npm 版本可能有问题）
  • npm（随 Node 安装）或 pnpm/yarn
  • Git（用于克隆主题与推送）
  • Hexo（可通过 npm 全局安装 hexo-cli）

验证命令：

1
2
3
node -v
npm -v
git --version

若输出版本号，说明工具安装成功。

■ 二、创建或进入博客项目（示例路径 D:\fj\Blog）

如果已存在项目，进入项目根目录（包含 _config.yml）：
PowerShell / Git Bash:

1
cd /d/fj/Blog

若无项目，初始化新项目：

1
2
3
4
5
npm install -g hexo-cli
mkdir D:\fj\Blog
cd D:\fj\Blog
hexo init
npm install

说明：

  • hexo init 会创建目录结构：_config.yml，source，scaffolds，themes 等。
  • npm install 会安装依赖（若出现依赖解析问题请参考“常见问题”章节）。

■ 三、安装并应用 Anzhiyu 主题（推荐用 git clone）

  1. 推荐：用 git clone（方便后续 git pull 更新主题）：
1
2
cd D:\fj\Blog
git clone -b main https://github.com/anzhiyu-c/hexo-theme-anzhiyu.git themes/anzhiyu
  1. 若想把主题作为子模块（便于版本控制）：
1
2
git submodule add -b main https://github.com/anzhiyu-c/hexo-theme-anzhiyu.git themes/anzhiyu
git submodule update --init --recursive
  1. 应用主题：编辑根目录 _config.yml，将 theme 设置为 anzhiyu：
    PowerShell（用 Notepad 打开并手动编辑）：
1
2
3
notepad .\_config.yml
# 在文件中找到 theme: 并改为
# theme: anzhiyu

说明：

  • 如果你用 npm 安装主题（npm install hexo-theme-anzhiyu），则主题可能在 node_modules 下，不需要 clone，但不便于更新或自定义。

■ 四、安装渲染器（pug / stylus）与常见依赖

Anzhiyu 主题使用 pug/stylus 等渲染器，安装命令：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

如果 npm 报错（如 arborist / matches / peer deps）：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save --legacy-peer-deps

或降级 npm（Windows 以管理员打开 PowerShell）：

1
npm install -g npm@9

说明：--legacy-peer-deps 会忽略 peerDependency 冲突，是常见临时解决方式；长期建议用 npm@9 或 pnpm/yarn。

■ 五、覆盖主题配置（详解：为什么、如何做、注意）

目的：把自定义配置放到项目根目录（例如 _config.anzhiyu.yml），避免 themes/anzhiyu 更新时被覆盖。

  1. 复制主题自带默认配置到根目录（复制操作按系统）：
  • macOS / Linux:
1
cp -rf ./themes/anzhiyu/_config.yml ./_config.anzhiyu.yml
  • Windows PowerShell:
1
Copy-Item -Path ".\themes\anzhiyu\_config.yml" -Destination ".\_config.anzhiyu.yml" -Force
  • Windows cmd:
1
copy themes\anzhiyu\_config.yml _config.anzhiyu.yml
  1. 编辑 _config.anzhiyu.yml（这是你日常修改的主题配置文件）：
1
notepad .\_config.anzhiyu.yml

或在 VSCode 中打开并修改。

  1. 覆盖规则与要点：
  • Hexo/主题的加载顺序通常为：主题默认配置（themes/anzhiyu/_config.yml） → 根目录覆盖文件（_config.anzhiyu.yml） → 根目录 _config.yml（站点级配置）。
  • 只要同名键存在于 _config.anzhiyu.yml，就会替换主题内对应键的值。
  • 若希望“覆盖为空”，不要删除键名，应该设置值为空字符串或 null，例如：
1
some_option: ""
  1. 保持更新时同步：
  • 主题更新后，开发者可能新增/重命名配置项。更新主题后请对比 themes/anzhiyu/_config.yml 与 _config.anzhiyu.yml，把新字段合并到你的 _config.anzhiyu.yml 中以启用新功能。

■ 六、本地生成与调试（含 –debug）

生成静态并本地预览：

1
2
3
4
hexo clean
hexo g --debug    # --debug 输出详细加载信息
hexo s
# 访问 http://localhost:4000

查看是否生效：

  • 在 hexo g --debug 输出中查找关于 anzhiyu 的加载行，确认是否读取了根目录 _config.anzhiyu.yml（很多主题会打印加载信息）。
  • 若样式不对或 JS 报错：在浏览器控制台查看 404/JS 错误，检查 public 目录是否包含主题资源（css/js/images）。

■ 七、SSH Key 与 GitHub 验证（用于自动部署）

生成 SSH key（如果尚未配置）：

1
2
ssh-keygen -t rsa -b 3072 -C "your-email@example.com"
# 默认为 C:\Users\<you>\.ssh\id_rsa 和 id_rsa.pub

复制公钥内容到 GitHub（Settings → SSH and GPG keys → New SSH key）：
PowerShell 打开并复制：

1
2
notepad $env:USERPROFILE\.ssh\id_rsa.pub
# 复制全部内容并粘贴到 GitHub 界面

验证 SSH 连接：

1
2
ssh -T git@github.com
# 成功示例：Hi username! You've successfully authenticated, but GitHub does not provide shell access.

■ 八、自动部署：hexo-deployer-git（推荐）

  1. 安装插件：
1
2
3
npm install hexo-deployer-git --save
# 如果出现依赖解析问题，追加 --legacy-peer-deps
# npm install hexo-deployer-git --save --legacy-peer-deps
  1. 在根目录 _config.yml 中加入 deploy 配置（替换为你的用户名）：
1
2
3
4
deploy:
  type: git
  repo: git@github.com:1298786483/1298786483.github.io.git
  branch: main

说明：

  • 对于用户/组织页（username.github.io），通常用 main 分支。
  • 如果你使用 HTTPS，则 repo: https://github.com/<user>/<user>.github.io.git，但要每次输入凭证或使用 PAT。
  1. 部署命令：
1
2
3
hexo clean
hexo g
hexo d

查看输出，若有 INFO Deploy done: git 则表示成功。然后访问 https://1298786483.github.io。

■ 九、手动部署（当插件安装失败或你想完全控制提交）

用 public 目录直接推送到 GitHub Pages：

1
2
3
4
5
6
7
8
9
hexo clean
hexo g
cd public
# 如果 public 不是 git 仓库
git init
git remote add origin git@github.com:1298786483/1298786483.github.io.git
git add .
git commit -m "Deploy: $(date)"
git push -f origin main

说明：

  • git push -f 强制覆盖远程分支，请确保你理解会覆盖远程内容。
  • 适合单人博客或临时解决部署插件问题。

■ 十、常见问题详尽排查（含命令与解决办法）

  1. npm 报错 Cannot read properties of null (reading 'matches') 或 arborist 错误：
  • 可能是 npm 的解析 bug。解决方案：
    • 先试 --legacy-peer-deps：
      1
      npm install hexo-deployer-git --save --legacy-peer-deps
    • 或降级 npm 到 9.x：
      1
      npm install -g npm@9
    • 或把 npm 缓存与前缀改到不含特殊字符路径（例如 D:\npm-cache D:\npm-global）：
      1
      2
      3
      4
      5
      New-Item -ItemType Directory -Path D:\npm-cache -Force
      New-Item -ItemType Directory -Path D:\npm-global -Force
      npm config set cache "D:\\npm-cache" --global
      npm config set prefix "D:\\npm-global" --global
      [Environment]::SetEnvironmentVariable('Path', $env:Path + ';D:\npm-global', 'User')
    • 关闭终端、重新打开，再试安装。
  1. Windows 用户目录包含特殊字符（如单引号 de'l'l）引发路径解析问题：
  • 最稳妥的做法：把博客项目放到不含特殊字符的路径，例如 D:\Blog 或 D:\projects\blog。
  • 或为开发创建一个新 Windows 用户（用户名不含特殊字符）。
  1. hexo g 后显示 0 files generated：
  • 说明 source 下没有需要处理的文件（未新增或修改）；若你期望生成，请确认 source/_posts 下有 .md 文件且 Front-matter 格式正确。
  • 若生成失败但应生成，查看 hexo g --debug 输出找错误。
  1. LF/CRLF 警告（Git 提示）：
  • 在 Windows 上统一换行策略：
    1
    2
    3
    git config --global core.autocrlf true
    git add --renormalize .
    git commit -m "Normalize line endings"
  1. 主题更新后设置丢失：
  • 你如果把配置修改在 themes/anzhiyu/_config.yml，更新主题时会被覆盖。正确做法是：复制主题 _config.yml 到根目录 _config.anzhiyu.yml 并在此文件中修改。
  1. 页面样式错乱或缺资源：
  • 用浏览器开发者工具检查网络 (Network) 是否有 404 请求；确认 public 目录是否包含缺失的资源。
  • 若主题生成的资源路径不正确，检查是否在 _config.anzhiyu.yml 中误改了 root、url 等字段。

■ 十一、建议的 _config.anzhiyu.yml 示例（可直接复制到根目录并按需修改）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# _config.anzhiyu.yml （示例）
title: 我的博客标题
subtitle: 记录与分享
description: 这是我的第一篇博客，用 Hexo + Anzhiyu 搭建
keywords: Hexo,Anzhiyu,博客
author: 站主
language: zh-CN
timezone: Asia/Shanghai

theme_color: "#1e90ff"
favicon: /images/favicon.ico

menu:
  首页: /
  归档: /archives/
  关于: /about/

social:
  github: https://github.com/1298786483
  email: mailto:your-email@example.com

# 例：隐藏一些默认元素（若主题支持）
show_ads: false
show_author: true
show_post_meta: true

注意：实际字段以 themes/anzhiyu/_config.yml 为准，阅读该文件了解主题支持的所有字段。

■ 十二、自动化脚本（Windows PowerShell 示例）

把下面内容保存为 deploy.ps1（放在项目根目录），以后只需双击或在 PowerShell 运行它即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# deploy.ps1 - 自动化生成并部署
param(
  [string]$mode = "hexo"  # hexo: 使用 hexo-deployer-git；manual: 手动 push public
)

Write-Host "Start deploy at $(Get-Date -Format o)"

hexo clean
hexo g

if ($mode -eq "hexo") {
  hexo d
} else {
  cd .\public
  if (!(Test-Path .git)) { git init; git remote add origin git@github.com:1298786483/1298786483.github.io.git }
  git add .
  git commit -m ("Deploy: " + (Get-Date).ToString("s")) -q
  git push -f origin main
}
Write-Host "Deploy finished at $(Get-Date -Format o)"

运行（PowerShell）：

1
2
.\deploy.ps1     # 默认使用 hexo-deployer-git
.\deploy.ps1 -mode manual   # 使用手动 public 推送方法

■ 十三、部署后检查清单

结束语

这篇超级详细教程覆盖了从安装主题、覆盖配置、渲染器安装、生成、部署、到常见问题与自动化脚本的完整流程。把本文件保存为 source/_posts/2025-11-19-hexo-anzhiyu-setup-detailed.md（或你喜欢的文件名）后运行：

1
2
hexo g
hexo s