📚 Hexo 博客完全操作手册 & 错误解决大全

基于 Maxkore 亲身经历的完整总结
涵盖日常操作、Git 工作流、各类报错解决方案
最后更新：2026年2月23日

📋 一、博客日常操作（标准流程）

1.1 写新文章

1
2
3
4
5
6
7
8

# 进入博客目录
cd /e/MyBlog

# 创建新文章（标题可以用中文）
hexo new "文章标题"

# 编辑文章（用 Typora/VS Code/记事本）
notepad source/_posts/文章标题.md

文章头部格式示例：

1
2
3
4
5
6

---
title: 文章标题
date: 2026-02-23 13:26:02
tags: [标签1, 标签2]
categories: [分类名]
---

1.2 ⚠️ 创建文章时的常见错误

错误示例：命令中包含特殊符号

1
2
3

# ❌ 错误：& 符号导致命令中断
hexo new "Hexo 博客 & 错误解决大全" && notepad source/_posts/Hexo 博客 & 错误解决大全.md
bash: 错误解决大全.md: command not found

✅ 正确方法 1：分两步执行（最稳妥）

1
2
3
4
5

# 第一步：创建文章
hexo new "文章标题"

# 第二步：打开编辑
notepad source/_posts/文章标题.md

✅ 正确方法 2：用引号保护特殊字符

1

hexo new "Hexo 博客 & 错误解决大全" && notepad "source/_posts/Hexo 博客 & 错误解决大全.md"

✅ 正确方法 3：文件名用短横线避免特殊字符

1

hexo new "hexo-complete-manual" && notepad source/_posts/hexo-complete-manual.md

如果文章已创建但打不开

1
2
3
4
5

# 查看刚创建的文件
ls -l source/_posts/

# 直接用文件名打开（注意用引号）
notepad "source/_posts/文章标题.md"

1.3 本地预览

1
2
3

hexo server
# 或指定端口
hexo s -p 4001

访问 http://localhost:4000 查看效果
按 Ctrl + C 停止预览

1.4 部署上线

1
2
3
4
5
6
7

# 标准三步曲
hexo clean      # 清理缓存
hexo generate   # 生成静态文件（可简写为 hexo g）
hexo deploy     # 部署到 GitHub（可简写为 hexo d）

# 一键完成
hexo clean && hexo g -d

1.5 修改文章

1
2
3
4
5

# 直接编辑源文件
notepad source/_posts/文章标题.md

# 重新部署
hexo clean && hexo g -d

1.6 删除文章

1
2
3
4
5

# 删除源文件
rm source/_posts/要删除的文章.md

# 清理并重新部署
hexo clean && hexo g -d

1.7 创建独立页面

1
2
3
4
5

# 创建“关于”页面
hexo new page about

# 创建自定义 HTML 页面
touch source/自定义页面.html

🌐 二、自定义域名配置与修复

2.1 首次配置自定义域名

在 GitHub 设置

1. 进入仓库 Settings → Pages
2. 在 Custom domain 输入你的域名（如 maxkore.bbroot.com）
3. 点击 Save
4. 勾选 Enforce HTTPS（等几分钟后出现）

创建 CNAME 文件（防止域名被清空）

1
2
3
4
5
6
7
8
9

# 进入博客目录
cd /e/MyBlog

# 创建 CNAME 文件（注意：没有扩展名）
echo "你的域名" > source/CNAME

# 验证文件内容
cat source/CNAME
# 应该只显示你的域名，没有多余空格或换行

2.2 ⚠️ 域名消失问题修复（重要！）

现象：每次部署后，GitHub Pages 设置里的自定义域名输入框被清空

原因：CNAME 文件缺失、内容错误或未被正确提交

修复步骤：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 1. 检查本地 CNAME 文件
cd /e/MyBlog
cat source/CNAME
# 如果不存在或内容错误，重新创建

# 2. 强制创建正确的 CNAME 文件（-n 参数避免多余换行）
echo -n "maxkore.bbroot.com" > source/CNAME

# 3. 确认内容（应该只有域名，没有额外换行）
cat source/CNAME

# 4. 提交到 Git 仓库
git add source/CNAME
git commit -m "修复 CNAME 文件，确保域名永久生效"
git push

# 5. 重新部署博客
hexo clean && hexo g -d

验证是否成功：

• 访问 GitHub 仓库：https://github.com/你的用户名/你的用户名.github.io
• 查看根目录是否有 CNAME 文件
• 点开文件，内容应为你的域名（如 maxkore.bbroot.com）
• 去 Settings → Pages，域名应该已经自动填好

2.3 域名消失的常见原因

2.4 永久解决方案

1
2
3
4
5
6
7
8
9
10
11

# 创建完美的 CNAME 文件（一次搞定）
cd /e/MyBlog
echo -n "maxkore.bbroot.com" > source/CNAME

# 添加到 Git 并推送
git add source/CNAME
git commit -m "添加 CNAME 文件，确保自定义域名永久生效"
git push

# 以后每次部署都会自动保留域名
hexo clean && hexo g -d

🔧 三、Git 工作流与同步

3.1 日常 Git 操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 查看当前状态
git status

# 添加所有更改
git add .

# 提交更改
git commit -m "提交说明"

# 推送到 GitHub
git push

# 拉取远程更新
git pull

3.2 完整推送流程

1
2
3
4

git add .
git commit -m "更新说明"
git pull origin master
git push origin master

3.3 强制推送（仅在必要时）

1

git push -f origin master

🚨 四、错误解决大全

4.1 YAML 解析错误

错误信息：

1

YAMLException: can not read a block mapping entry

原因：文章开头的配置格式错误
解决：

• 检查 : 后面是否有空格
• 确保缩进正确
• 示例正确格式：

  1 2 3

  title: 正确格式 # ✅ 冒号后有空格 tags: [标签] # ✅ 正确 tags: [标签] # ❌ 错误

4.2 部署失败 - 网络问题

错误信息：

1

fatal: unable to access '...': Recv failure: Connection was reset

原因：GitHub 网络波动
解决：

1
2
3
4
5
6
7
8
9

# 方法1：稍后重试
hexo clean && hexo g -d

# 方法2：手动 Git 推送
git add .
git commit -m "更新"
git push

# 方法3：切换网络（WiFi换热点）

4.3 Git 推送被拒绝

错误信息：

1

! [rejected] master -> master (fetch first)

原因：远程有本地没有的更新
解决：

1
2

git pull origin master
git push origin master

4.4 合并冲突

错误信息：

1

Automatic merge failed; fix conflicts and then commit the result.

现象：处于 (master|MERGING) 状态
解决：

1
2
3
4
5
6
7
8
9
10
11

# 1. 查看冲突文件
git status

# 2. 添加已解决的文件
git add .

# 3. 完成合并
git commit -m "解决合并冲突"

# 4. 推送
git push origin master

4.5 子模块错误

错误信息：

1

fatal: No url found for submodule path '.deploy_git' in .gitmodules

原因：Git 误将文件夹当作子模块
解决：

1
2
3
4
5
6

# 彻底清理
rm -rf .gitmodules
git rm --cached .deploy_git
git add .
git commit -m "移除子模块配置"
git push

4.6 SSH 密钥问题

错误信息：

1

git@github.com: Permission denied (publickey)

原因：SSH 密钥未配置或密码错误
解决：

1
2
3
4
5
6
7
8
9

# 生成新密钥（无密码）
ssh-keygen -t rsa -b 4096 -C "你的邮箱"
# 一直按回车（不设密码）

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

# 复制公钥添加到 GitHub
# Settings → SSH and GPG keys → New SSH key

4.7 Token 认证问题

错误信息：

1

remote: Invalid username or token.

原因：Token 错误或过期
解决：

1
2
3

# 重新生成 Token 后使用
git remote set-url origin https://用户名:新token@github.com/用户名/仓库名.git
git push

4.8 本地预览端口被占用

错误信息：

1

Error: listen EADDRINUSE

解决：

1
2

# 换端口启动
hexo s -p 4001

4.9 文章不显示

现象：部署成功但文章没出现
原因：文章头部格式错误
解决：

• 检查 date 格式是否正确
• 确保 title 不为空
• 运行 hexo clean 后重新生成

📝 五、配置文件详解

5.1 主配置文件 _config.yml

1
2
3
4
5
6
7
8
9
10
11
12
13

# 网站信息
title: 博客标题
subtitle: 副标题
description: 描述
author: 作者名
language: zh-CN
timezone: Asia/Shanghai

# 部署配置
deploy:
  type: git
  repo: git@github.com:用户名/用户名.github.io.git
  branch: master

5.2 NexT 主题配置 themes/next/_config.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 菜单
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  tags: /tags/ || fa fa-tags
  about: /about/ || fa fa-user

# 头像
avatar:
  url: /images/avatar.gif

# 社交链接
social:
  GitHub: https://github.com/你的用户名 || fab fa-github

🧹 六、日常维护清单

6.1 每周任务

• 写新文章
• 本地预览确认格式
• 部署上线

6.2 每月任务

• 检查域名续期状态
• 更新依赖 npm update
• 备份 source/ 和 _config.yml

6.3 域名维护（重要）

• 确认 source/CNAME 文件存在且内容正确
• 每月初检查 GitHub Pages 设置里自定义域名是否还在
• 如果消失，按 2.2 节步骤修复

📌 七、常用命令速查表

💡 八、经验总结

8.1 黄金法则

1. 写文章前：先 git pull 确保最新
2. 部署前：先 hexo clean 避免缓存问题
3. 遇到错误：先看错误日志，再搜解决方案
4. 重要操作前：先备份 source/ 文件夹
5. 域名配置：永远在 source/ 下放 CNAME 文件

8.2 创建文章注意事项

8.3 常见误区

• ❌ 直接在 GitHub 网页修改文件
• ❌ 忘记 : 后的空格
• ❌ 提交 node_modules/ 到仓库
• ❌ 推送前不拉取远程更新
• ❌ 忘记检查 CNAME 文件（导致域名消失）
• ❌ 命令中包含 & 等特殊字符不加处理

8.4 最佳实践

• ✅ 每次写文章前 git pull
• ✅ 每次部署用 hexo clean && hexo g -d
• ✅ 定期备份 source/ 文件夹
• ✅ 写提交信息时用中文说明
• ✅ 每月检查一次 CNAME 文件（防患未然）
• ✅ 创建文章时分两步执行（避免命令解析错误）

🎉 九、恭喜！

你现在拥有：

• ✅ 完整的博客操作知识
• ✅ 所有常见错误的解决方案
• ✅ 自定义域名永久保留的秘籍
• ✅ 创建文章时的避坑指南
• ✅ 一套标准化的发布流程
• ✅ 可随时查阅的维护手册

从此写博客只需三步：

1
2
3

hexo new "新文章"        # 写
hexo clean && hexo g -d  # 发
git push                 # 备（可选）

域名永久保留：

1

echo -n "你的域名" > source/CNAME  # 一次配置，永久有效

创建文章避坑：

1
2
3

# 稳妥的两步法
hexo new "文章标题"
notepad "source/_posts/文章标题.md"

本手册由 Maxkore 基于真实经历编写
博客示例：https://maxkore.bbroot.com
最后更新：2026年2月23日
特别章节：自定义域名消失问题 & 创建文章避坑指南

🚀 从零开始：免费搭建个人博客完整指南

用 Node.js + Hexo + GitHub Pages，无需服务器，无需域名费用
适合完全零基础的新手，手把手教学

📋 一、准备工作（15分钟）

1.1 注册 GitHub 账号

1. 访问 GitHub官网
2. 点击 Sign up，输入用户名（如 yourname）、邮箱、密码
3. 验证邮箱后完成注册

1.2 安装必要软件

1.3 验证安装

打开 Git Bash（安装 Git 后会在右键菜单出现），输入：

1
2

node -v     # 显示版本号如 v18.18.0 即成功
git --version  # 显示版本号如 git 2.42.0 即成功

🏗️ 二、本地搭建博客（20分钟）

2.1 安装 Hexo

1

npm install -g hexo-cli

2.2 初始化博客

1
2
3
4
5
6
7
8

# 创建博客文件夹（名字自取）
hexo init myblog

# 进入博客目录
cd myblog

# 安装依赖
npm install

2.3 本地预览

1
2

hexo g      # 生成静态文件
hexo s      # 启动本地服务器

打开浏览器访问 http://localhost:4000，看到博客首页即成功
按 Ctrl + C 可停止预览

🎨 三、更换漂亮主题（10分钟）

以广受欢迎的 NexT 主题 为例：

3.1 下载主题

1

git clone https://github.com/theme-next/hexo-theme-next themes/next

3.2 启用主题

编辑博客根目录的 _config.yml 文件：

1

theme: next

3.3 应用主题

1

hexo clean && hexo g && hexo s

刷新 http://localhost:4000 查看新主题

☁️ 四、部署到 GitHub Pages（15分钟）

4.1 创建 GitHub 仓库

1. 登录 GitHub，点击右上角 + → New repository
2. 仓库名必须填：你的用户名.github.io
   （例如用户名为 yourname，就填 yourname.github.io）
3. 选择 Public，点击 Create repository

4.2 安装部署插件

1

npm install hexo-deployer-git --save

4.3 配置部署信息

编辑博客根目录 _config.yml，修改 deploy 部分：

1
2
3
4

deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main  # 或 master，看你的仓库默认分支

4.4 生成并部署

1

hexo clean && hexo g -d

4.5 访问博客

1

https://你的用户名.github.io

等待 2-5 分钟，就能看到博客上线了！🎉

🌐 五、绑定自定义域名（可选）

5.1 注册免费域名（以 DNSHe 为例）

1. 访问 DNSHe 注册账号
2. 选择免费后缀如 bbroot.com、de5.net
3. 填写前缀，如 myblog.bbroot.com
4. 完成注册

5.2 添加 DNS 记录

在 DNSHe 后台添加 4 条 A 记录：

（可选）添加 CNAME 让 www 也能访问：

5.3 在 GitHub 设置域名

1. 进入仓库 Settings → Pages
2. Custom domain 输入你的域名（如 myblog.bbroot.com）
3. 点击 Save
4. 勾选 Enforce HTTPS（等几分钟后出现）

5.4 创建 CNAME 文件（防止域名被清空）

1
2
3
4
5

cd myblog
echo "你的域名" > source/CNAME
git add .
git commit -m "添加 CNAME 文件"
git push

✍️ 六、日常写作与维护

6.1 写新文章

1
2

cd myblog
hexo new "文章标题"

编辑 source/_posts/文章标题.md

6.2 部署更新

1

hexo clean && hexo g -d

6.3 常用命令速查

🧩 七、常见问题解决

Q1：部署后页面还是旧的

• 等待 2-5 分钟
• 按 Ctrl + F5 强制刷新
• 检查 Actions 页面是否构建成功

Q2：自定义域名被清空

• 检查 source/CNAME 文件是否存在
• 文件内容应为 你的域名（不要加 http://）

Q3：git push 提示权限错误

• 使用 Personal Access Token 代替密码
• 或配置 SSH 密钥（参考网上教程）

Q4：本地预览正常，线上 404

• 检查 GitHub Pages 是否开启（Settings → Pages）
• 确认分支选择正确（master 或 main）
• 检查 .nojekyll 文件是否存在

🔐 八、注意事项

1. 配置文件格式：_config.yml 里冒号后面必须加空格
2. 不要提交敏感信息：API 密钥、token 不要上传到 GitHub
3. 定期备份：source/ 和 _config.yml 是最重要的文件
4. 域名续期：免费域名每年需手动续期（或设置自动脚本）

📚 九、进阶学习资源

• Hexo 官方文档
• NexT 主题文档
• GitHub Pages 官方指南
• Markdown 语法入门

🎉 十、恭喜！

按照本指南，你已经拥有：

• ✅ 一个完全属于自己的技术博客
• ✅ 免费托管在 GitHub Pages
• ✅ 可绑定自定义域名
• ✅ 支持 HTTPS 安全访问
• ✅ 完整的写作发布流程

现在开始写你的第一篇文章吧！ 🚀

本指南由 Maxkore 基于亲身经历编写
博客示例：https://maxkore.bbroot.com
最后更新：2026年2月23日

🌐 Maxkore 博客网站维护说明书

一份全面、易懂的 Hexo + GitHub Pages 博客维护指南
适用于日常写作、站点配置、故障排查与内容管理

📁 一、博客目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13

MyBlog/
├── _config.yml          # 博客主配置文件（重要！）
├── package.json          # 依赖包管理
├── scaffolds/            # 文章模板（post/page/draft）
├── source/               # 内容源文件（核心！）
│   ├── _posts/           # 文章存放处（Markdown）
│   ├── 自定义页面/        # 如 CTMIF/、极客索引.html
│   └── CNAME              # 自定义域名文件
├── themes/                # 主题文件夹（如 next）
│   └── next/              # NexT 主题配置
├── public/                 # 生成的静态文件（不用管）
├── .deploy_git/            # 部署临时文件（不用管）
└── .gitignore              # Git 忽略规则

✍️ 二、日常写作与发布

1. 创建新文章

1
2

cd /e/MyBlog
hexo new "文章标题"

会在 source/_posts/ 生成 .md 文件

2. 编辑文章

• 用 Typora、VS Code 或记事本打开
• 文件开头格式示例：

  1 2 3 4 5

  --- title: 文章标题 date: 2026-02-23 13:26:02 tags: [标签1, 标签2] ---

3. 本地预览

1

hexo server

访问 http://localhost:4000 查看效果
按 Ctrl + C 停止预览

4. 部署上线

1

hexo clean && hexo g -d

清理缓存 → 生成静态文件 → 推送到 GitHub

5. 删除文章

1
2

rm source/_posts/要删除的文章.md
hexo clean && hexo g -d

📄 三、自定义页面（HTML / 独立页面）

1. 创建独立页面（如“关于”）

1

hexo new page about

生成 source/about/index.md，访问 https://maxkore.bbroot.com/about/

2. 创建自定义 HTML 文件

直接在 source/ 下创建 .html 文件：

1

touch "/e/MyBlog/source/极客索引.html"

写入 HTML 内容后部署：

1

hexo clean && hexo g -d

访问 https://maxkore.bbroot.com/极客索引.html

🎨 四、主题与样式配置

NexT 主题常用配置（themes/next/_config.yml）

1
2
3
4
5
6
7
8
9
10
11
12
13

# 菜单
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  tags: /tags/ || fa fa-tags

# 头像
avatar:
  url: /images/avatar.gif

# 社交链接
social:
  GitHub: https://github.com/Maxkore-Geek || fab fa-github

主配置文件（_config.yml）

1
2
3
4
5
6
7
8
9
10
11

title: Maxkore的博客
subtitle: 代码之外，思考之上。
author: Maxkore
language: zh-CN
timezone: Asia/Shanghai

# 部署配置
deploy:
  type: git
  repo: git@github.com:Maxkore-Geek/Maxkore-Geek.github.io.git
  branch: master

🔧 五、常见故障排查

🔐 六、Git 与 GitHub 维护

日常同步

1
2
3
4

git status          # 查看当前状态
git add .           # 添加所有更改
git commit -m "说明" # 提交
git push            # 推送到 GitHub

分支与远程

1
2

git branch          # 查看当前分支
git remote -v       # 查看远程仓库地址

强制推送（仅在必要时）

1

git push -f origin master

🔄 七、域名与 HTTPS

当前域名

• 主域名：maxkore.bbroot.com
• 备用域名：maxkore-geek.github.io

GitHub Pages 设置

• 仓库 → Settings → Pages
• Branch: master → / (root)
• Custom domain: maxkore.bbroot.com
• ✅ Enforce HTTPS 已启用

DNS 记录（DNSHe 后台）

⏱️ 八、自动续期任务（Windows 计划）

脚本位置

1

E:\服务器(勿删)\renew.py

任务计划设置

• 名称：DNSHE 域名自动续期
• 触发器：每月 1 日 09:00
• 操作：python "E:\服务器(勿删)\renew.py"

日志查看

1

E:\服务器(勿删)\renew.log

📌 九、日常写作快速参考

一条命令搞定

1

cd /e/MyBlog && hexo new "新文章" && notepad source/_posts/新文章.md

写完保存后：

1

hexo clean && hexo g -d

常用命令速查

🧠 十、经验总结

1. 写文章永远在 source/_posts/
2. 改配置永远在 _config.yml 或主题的 _config.yml
3. 部署永远用 hexo clean && hexo g -d
4. 404 先等 2 分钟，再 Ctrl + F5
5. Git 冲突先 git pull，再 git push
6. 网络问题重试几次，或换热点

最后更新：2026年2月23日
维护人：Maxkore
博客地址：https://maxkore.bbroot.com