本文是当前博客项目的日常操作备忘。项目基于 Hexo 8.1.2，主题配置为 Butterfly，站点语言为 zh-CN，时区为 Asia/Shanghai。

项目结构

1
2
3
4
5
6
7
8
9
10
11
.
├── _config.yml              # Hexo 主配置：站点信息、目录、URL、部署等
├── _config.butterfly.yml    # Butterfly 主题配置
├── package.json             # npm 脚本和依赖
├── scaffolds/               # 新文章、新页面、草稿的模板
├── source/
│   ├── _posts/              # 已发布文章
│   ├── _drafts/             # 草稿
│   ├── categories/          # 分类页
│   └── tags/                # 标签页
└── themes/                  # 主题目录，Butterfly 通过 git submodule 管理

Hexo 官方约定中，_config.yml 是站点配置，source/ 放内容，scaffolds/ 是新建内容时使用的模板，themes/ 用来存主题。当前项目还单独维护了 _config.butterfly.yml 作为 Butterfly 主题配置。

首次拉取或换电脑恢复

1
2
3
4
git clone <本仓库地址>
cd BlogSource
git submodule update --init --recursive
npm install

如果运行时报主题不存在、页面样式缺失，先检查 themes/butterfly 是否有内容。当前仓库的 .gitmodules 指向 themes/butterfly，所以完整恢复项目时需要初始化子模块。

常用命令

当前 package.json 已经封装了常用 Hexo 命令：

场景 推荐命令 等价 Hexo 命令 说明
本地预览 npm run server hexo server 默认访问 http://localhost:4000/
生成静态站点 npm run build hexo generate 输出到 public/
清理缓存和构建产物 npm run clean hexo clean 清理 db.json 和 public/
部署 npm run deploy hexo deploy 使用 _config.yml 中的 deploy 配置

端口被占用时：

1
npm run server -- -p 5000

需要在预览时显示草稿：

1
npm run server -- --draft

构建前如果怀疑缓存有问题，直接走完整流程：

1
2
npm run clean
npm run build

新建文章

本项目新增文章必须通过 Hexo CLI 创建，不直接手动新建 source/_posts/*.md。正确流程是先让 Hexo 根据 scaffolds/ 生成文件，再编辑生成出来的 Markdown。

文章文件名统一使用英文 kebab-case，也就是小写英文单词加连字符，例如 hexo-usage-guide.md。中文标题写在 Front Matter 的 title 里，不放进文件名。

默认布局是 post，所以以下两条命令效果接近：

1
2
npx hexo new "hexo-usage-guide"
npx hexo new post "hexo-usage-guide"

生成位置取决于 _config.yml：

1
2
new_post_name: :title.md
default_layout: post

也就是说，新文章会生成到 source/_posts/hexo-usage-guide.md 这类文件。生成后再把 Front Matter 里的 title 改成中文展示标题。

建议使用这种 Front Matter：

1
2
3
4
5
6
7
---
title: 文章标题
date: 2026-06-14 14:30:00
categories: development-tools
tags:
  - hexo
---

注意点：

  • tags 和 categories 只对文章生效，页面不使用。
  • categories 表示分类，tags 表示标签。
  • 分类和标签值统一使用英文 slug，例如 development-tools、frontend、hexo，避免生成中文路径。
  • 现有文章里同时出现过 category 和 categories；新增文章建议优先使用 Hexo 官方文档里的 categories。
  • 技术文章里命令、路径、配置项使用代码格式，例如 npm run build、_config.yml。

草稿流程

草稿同样通过 Hexo CLI 创建，不手动新建草稿文件。

创建草稿：

1
npx hexo new draft "草稿标题"

草稿会放到 source/_drafts/。默认不会展示，因为当前配置是：

1
render_drafts: false

本地预览草稿：

1
npm run server -- --draft

发布草稿：

1
npx hexo publish "草稿文件名"

例如草稿文件是 source/_drafts/idea的配置.md，发布时可以执行：

1
npx hexo publish "idea的配置"

发布后文件会移动到 source/_posts/。

新建页面

创建普通页面：

1
npx hexo new page about

页面默认会生成类似 source/about/index.md 的结构。当前项目已经有：

  • source/categories/index.md
  • source/tags/index.md

分类页和标签页通常只需要保留页面文件，文章的分类和标签由每篇文章的 Front Matter 驱动。

图片和静态资源

当前项目配置为：

1
post_asset_folder: false

所以最简单的两种方式是：

  1. 继续沿用现有文章的外部图床链接。
  2. 把少量图片放在 source/images/，然后在文章中引用：
1
![图片说明](/images/example.png)

如果以后要改成每篇文章一个资源目录，可以把 _config.yml 里的 post_asset_folder 改为 true。开启后，hexo new 会为每篇新文章创建同名资源目录，文章中可使用 Hexo 的资源标签语法：

1
{% asset_img example.jpg 图片说明 %}

这个项目目前没有开启该模式，除非要统一迁移图片管理方式，不建议临时改。

本地预览

启动：

1
npm run server

默认地址：

1
http://localhost:4000/

Hexo server 会监听文件变化并自动更新，通常不需要每次改文章都重启。若页面没有刷新，可以手动停止服务后重新运行；仍异常时执行：

1
2
npm run clean
npm run server

构建和部署

生成静态文件：

1
npm run build

生成内容会进入 public/。该目录是构建产物，已经被 .gitignore 忽略，不需要提交。

当前 _config.yml 的部署配置是：

1
2
3
4
deploy:
  type: 'git'
  repo: https://github.com/xiongxingqi/xiongxingqi.github.io.git
  branch: master

项目已安装 hexo-deployer-git。稳妥部署流程：

1
2
3
npm run clean
npm run build
npm run deploy

也可以让 Hexo 在部署前生成：

1
npm run deploy -- --generate

如果部署失败，优先检查：

  • GitHub 账号是否有目标仓库权限。
  • 当前网络是否能访问 GitHub。
  • 目标仓库和分支是否仍然是 _config.yml 中配置的地址和 master。

常见问题

hexo: command not found

先安装依赖：

1
npm install

然后优先使用 npm run ... 或 npx hexo ...，不要依赖全局安装的 Hexo。

页面样式不对或提示找不到主题

检查主题子模块：

1
git submodule update --init --recursive

再重新构建：

1
2
npm run clean
npm run build

端口 4000 被占用

换端口：

1
npm run server -- -p 5000

文章顺序不对

Hexo 默认按日期倒序展示文章。检查文章 Front Matter 中的 date，本项目的日期格式建议沿用：

1
date: 2026-06-14 14:30:00

文章发布后没有出现

检查：

  • 文件是否在 source/_posts/，而不是 source/_drafts/。
  • Front Matter 是否完整闭合。
  • 是否设置了 published: false。
  • 是否需要执行 npm run clean && npm run build 清缓存。

配置改哪里

  • 站点标题、作者、语言、时区、URL、永久链接、部署：改 _config.yml。
  • Butterfly 菜单、侧边栏、头像、社交链接、评论、样式：改 _config.butterfly.yml。
  • 新文章默认 Front Matter：改 scaffolds/post.md。
  • npm 命令：改 package.json 的 scripts。

发布相关配置变更前，尤其是 url、permalink、deploy.repo、deploy.branch，建议先确认目标站点和 GitHub Pages 仓库没有变化。

官方文档参考