Chemmy's Blog

chengming0916@outlook.com

发表于 更新于

环境准备

本地安装 Git NodeJS

检查环境

1
2
3
4
5
git -v

node -v

npm -v

切换镜像站,具体参考NPM配置国内源

1
npm config set registry https://registry.npmmirror.com

Hexo环境搭建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pnpm install -g hexo-cli                # 安装Hexo cli工具

hexo init                            # 初始化博客环境
npm install                          # 安装依赖库

# 插件
npm install hexo-asset-img           # 头像
npm install hexo-auto-category       # 自动分类
npm install hexo-generator-searchdb  # 生成搜索数据库
npm install hexo-backlink            # Obsdian链接转换
npm install hexo-deploy-git          # git自动发布
npm install hexo-theme-next          # hexo NexT主题
npm install hexo-server              # hexo服务器
npm install hexo-next-giscus         # giscus评论组件
npm install hexo-wordcount           # 字数统计

Hexo 配置

参考官方文档

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
26
27
28
29
30
31
...
theme: next     # 配置主题next

giscus:         # 评论配置
  enable: true
  repo:  # Github repository name
  repo_id: # Github repository id
  category: # Github discussion category
  category_id: # Github discussion category id
  # Available values: pathname | url | title | og:title
  mapping: title
  # Available values: 0 | 1
  reactions_enabled: 1
   # Available values: 0 | 1
  emit_metadata: 1
  # Available values: light | light_high_contrast | light_protanopia | light_tritanopia | dark | dark_high_contrast | dark_protanopia | dark_tritanopia | dark_dimmed | preferred_color_scheme | transparent_dark | noborder_light | noborder_dark | noborder_gray | cobalt | purple_dark
  theme: light
  # Available values: en | zh-CN
  lang: zh-CN
  # Place the comment box above the comments
  input_position: bottom
  # Load the comments lazily
  loading: lazy
  
deploy:   # 发布配置
  - type: git
    repo:        # 仓库发布地址
    branch: main # 发布分支
    name:        # git用户名 git config user.name <username>
    email:       # git邮箱 git config user.email <email>
...

注意： 评论部分需要借助Github Discussions, 参考Hexo博客配置Giscus评论

Hexo主题配置

安装主题后从npm_modules/<主题名>/文件夹中复制_config.yml到博客根目录并重命名为_config.next.yml,当博客deploy时回自动应用主题配置，一下主题修改都基于此文件进行。

设置语言

NexT主题支持多种语言，只需要编辑_config.next.yml中的language设置即可

语言 代码 设定示例
English en language: en
简体中文 zh-CN（注：zh-Hans已经无法使用） language: zh-CN
Frangais fr-FR language: fr-FR
Portugues pt language: pt
或者
language:pt-BR
繁體中文 zh-hk
或者
zh-tw		 language: zh-hk
Pycckmi 93bIK ru language: ru
Deutsch de language: de
日本語 ja language: ja
Indonesian id language: id
Korean ko language: ko
如果需要添加非内置的字段需要手动添加翻译文件，例如中文的翻译文件路径为node_modules/next/languages/zh-CN.yml

设置关于

在source/about/index.md中添加如下内容

1
2
3
4
5
6
---
title: 关于
date: 2025-08-27 00:00:00
---

<个人信息>

选择Scheme

Scheme 是 NexT 提供的一种特性，借助于 Scheme，NexT 为你提供多种不同的外观。同时，几乎所有的配置都可以 在 Scheme 之间共用。目前 NexT 支持三种 Schem

  • Muse - 默认 Scheme
  • Mist - Muse 的紧凑版本
  • Pisces - 双栏 Scheme
  • Gemini

菜单配置

菜单配置包括三个部分，第一是菜单项（名称和链接），第二是菜单项的显示文本，第三是菜单项对应的图标。 NexT 使用的是 Font Awesome 提供的图标， Font Awesome 提供了 600+ 的图标，可以满足绝大的多数的场景，同时无须担心在 Retina 屏幕下 图标模糊的问题。

1
2
3
4
5
6
7
8
menu: home: / || home 
categories: /categories/ || th 
archives: /archives/ || archive 
tags: /tags/ || tags 
#schedule: /schedule/ || calendar 
#sitemap: /sitemap.xml || sitemap 
#commonweal: /404/ || heartbeat 
about: /about/ || user

NexT 默认的菜单项有（标注 * 的项表示需要手动创建这个页面）：

注意: 若站点运行在子目录中，请将链接前缀的 / 去掉。

键值 设定值 显示文本（简体中文）
home home: / 主页
archives archives: /archives 归档页
categories categories: /categories 分类页 *
tags tags: /tags 标签页 *
about about: /about 关于页面*
commonweal commonweal: /404.html 公益 404 !

侧栏配置

默认情况下，侧栏仅在文章页面（拥有目录列表）时才显示，并放置于右侧位置。配置具体如下

1
2
3
4
5
6
7
...

sidbar:
  position: left     # 配置侧栏居左
  display: post      # 侧栏显示行为

...

侧栏显示位置支持

  • left: 居左显示
  • right: 居右显示

侧栏显示行为支持

  • post 默认行为，在文章页面（拥有目录列表）时显示
  • always 所有页面都显示
  • hide 在所有页面中都隐藏（可以手动展开）
  • remove 完全移除

注册Github账号,Gitea账号(可选)
[^注] Github由于网络问题会经常无法链接，可使用Gitea作为中转，先将代码提交道Gitea，然后Gitea配置自动推送到Github

设置头像

1
avatar: /images/avatar.jpg

头像地址如果是以/起始则表示头像图片放置在博客发布后的目录下，例如测试博客地址是http://localhost:4000,头像图片地址为http://localhost:4000/images/avatar.jpg
此配置需要在博客的source/images目录中放置头像图片avatar.jpg

侧边栏社交链接

1
2
3
4
5
6
7
8
9
10
social:
  #GitHub: https://github.com/<username> || fab fa-github
  #E-Mail: <email> || fa fa-envelope
  #Weibo: https://weibo.com/yourname || fab fa-weibo
  #Twitter: https://twitter.com/yourname || fab fa-twitter
  #FB Page: https://www.facebook.com/yourname || fab fa-facebook
  #StackOverflow: https://stackoverflow.com/yourname || fab fa-stack-overflow
  #YouTube: https://youtube.com/yourname || fab fa-youtube
  #Instagram: https://instagram.com/yourname || fab fa-instagram
  #Skype: skype:yourname?call|chat || fab fa-skype

next主题默认支持的社交链接 ||符号后是链接的图标

使用已有配置放开注释即可，如果要添加默认不存在链接示例如下

1
2
social:
  微信: https://wx.qq.com || weixin

注意: 图标对应的名称是FontAwesom图标的名称（不必带 fa- 前缀）

打赏功能

1
2
3
4
# Reward 
reward: 
  wechatpay: /images/custom/wechatpay.jpg 
  alipay: /images/custom/alipay.jpg

放开此部分注释并在source/images中放入收款码图片

站点建立时间

1
2
footer:
  since: 2025

订阅微信公众号

1
2
3
4
5
# Wechat Subscriber 
wechat_subscriber: 
  enabled: true 
  qcode: /images/wechat-qcode.jpg 
  description: 欢迎您扫一扫上面的微信公众号，订阅我的博客！

放开此部分注释，并在source/images中放入公众号二维码

注意: 此功能需要NexT版本在5.0.1之后

设置动画

NexT 默认开启动画效果，效果使用 JavaScript 编写，因此需要等待 JavaScript 脚本完全加载完毕后才会显示内容。 如果您比较在乎速度，可以将设置此字段的值为 false 来关闭动画。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Use velocity to animate everything. 
motion: 
  enable: true 
  async: true 
  transition: 
    # Transition variants: 
    # fadeIn | fadeOut | flipXIn | flipXOut | flipYIn | flipYOut | flipBounceXIn | flipBounceXOut | flipBounceYIn | flipBounceYOut 
    # swoopIn | swoopOut | whirlIn | whirlOut | shrinkIn | shrinkOut | expandIn | expandOut 
    # bounceIn | bounceOut | bounceUpIn | bounceUpOut | bounceDownIn | bounceDownOut | bounceLeftIn | bounceLeftOut | bounceRightIn | bounceRightOut 
    # slideUpIn | slideUpOut | slideDownIn | slideDownOut | slideLeftIn | slideLeftOut | slideRightIn | slideRightOut 
    # slideUpBigIn | slideUpBigOut | slideDownBigIn | slideDownBigOut | slideLeftBigIn | slideLeftBigOut | slideRightBigIn | slideRightBigOut 
    # perspectiveUpIn | perspectiveUpOut | perspectiveDownIn | perspectiveDownOut | perspectiveLeftIn | perspectiveLeftOut | perspectiveRightIn | perspectiveRightOut 
    post_block: fadeIn 
    post_header: slideDownIn 
    post_body: slideDownIn 
    coll_header: slideLeftIn # Only for Pisces | Gemini. 
    sidebar: slideUpIn

设置全文阅读

在首页显示一篇文章的部分内容，并提供一个链接跳转到全文页面是一个常见的需求。 NexT 提供三种方式来控制文章在首页的显示方式。

  • 在文章中使用 <!-- more --> 手动进行截断，Hexo 提供的方式 推荐。
  • 在文章的 front-matter 中添加 description，并提供文章摘录
  • 自动形成摘要，需要添加如下配置
    1
    2
    3
    4
    5
    # Automatically Excerpt. Not recommend. 
    # Please use <!-- more --> in the post to control excerpt accurately. 
    auto_excerpt: 
      enable: true 
      length: 150

设置字数统计/阅读时长

在_config.yml中配置如下

1
2
3
4
5
6
7
8
# Post wordcount display settings 
# Dependencies: https://github.com/willin/hexo-wordcount 
post_wordcount: 
  item_text: true 
  wordcount: true 
  min2read: true 
  totalcount: false 
  separated_meta: true

加载进度条

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Progress bar in the top during page loading.
pace: true
# Themes list:
#pace-theme-big-counter
#pace-theme-bounce
#pace-theme-barber-shop
#pace-theme-center-atom
#pace-theme-center-circle
#pace-theme-center-radar
#pace-theme-center-simple
#pace-theme-corner-indicator
#pace-theme-fill-left
#pace-theme-flash
#pace-theme-loading-bar
#pace-theme-mac-osx
#pace-theme-minimal
# For example
# pace_theme: pace-theme-center-simple
pace_theme: pace-theme-minimal

搜索服务

在_config.yml中配置如下

1
2
3
4
5
6
# hexo-generator-searchdb 
search: 
  path: search.xml 
  field: post 
  format: html 
  limit: 10000

在_config.next.yml中配置如下

1
2
3
4
5
6
7
8
9
# Local search 
# Dependencies: https://github.com/flashlab/hexo-generator-search 
local_search: 
  enable: true 
  # if auto, trigger search by changing input 
  # if manual, trigger search by pressing enter key or search button   
  trigger: auto 
  # show top n results per article, show all results by setting to -1 
  top_n_per_article: 1

参考
官方文档
Hexo 博客使用 Next 主题及美化 | Jiz4oh’s Life

发表于 更新于

前言

作为技术博主，博客的高效维护与部署一直是我关注的重点。近期在维护博客时，我遇到了两个核心问题：

  1. 内容管理混乱：草稿箱文件堆积，缺乏分类标准，甚至因误操作破坏了原有配置；
  2. 兼容性局限：计划将文章同步至 FastGPT 等 AI 知识库时，发现官方推荐的 Hexo 部署方案（源码与静态文件混存）中，冗余的 public 目录会干扰 RAG 系统提取内容，且源码与发布产物耦合易引发冲突。

为解决这些问题，我采用了源码与发布分离的部署架构：将 Markdown 源文件单独存放在一个仓库，通过 GitHub Actions 自动在另一个仓库构建并发布静态文件。这种方式的优劣对比如下：

方案 优点 缺点
官方混仓部署 支持本地手动 / 自动发布，预览方便，配置简单 仓库体积大，源码与产物混合，不利于二次利用
本文分离部署 源码纯净、产物独立，兼容 AI 知识库，自动构建 本地预览需搭测试环境，配置较复杂（双仓库 + 鉴权）

部署核心思路

核心逻辑：当源码仓库收到推送时，GitHub Actions 自动将源文件检出到 source/_posts，并从 _hexo 目录复制配置文件还原 Hexo 环境，最终执行构建与发布。

文件结构设计（源码仓库）：

1
2
3
4
5
6
7
8
|-- _hexo/ # Hexo 核心配置目录 
| |-- _config.yml # Hexo 主配置 
| |-- _config.next.yml # NexT 主题配置 
| |-- package.json # Node 环境依赖 
| |-- scaffolds/ # 文章模板（draft/page/post.md） 
| |-- static/ # 静态资源（头像、支付码等） 
|-- .github/workflows/ # GitHub Actions 工作流配置 
|-- .obsidian/ # Obsidian 编辑器配置（可选）

详细部署步骤

1. 生成 SSH 密钥对（用于仓库间鉴权）

需要生成一对 SSH 密钥，用于源码仓库向发布仓库推送构建结果：

1
ssh-keygen -t rsa -C "<github 注册邮箱>"

执行后会在以下路径生成两个文件：

  • 私钥：~/.ssh/id_rsa（Linux/Mac）或 C:\Users\<用户名>\.ssh\id_rsa（Windows）
  • 公钥：~/.ssh/id_rsa.pub（同上路径）

注意：.ssh为隐藏目录，需要修改系统设置显示此文件夹

2. 准备两个仓库

仓库 1：源码仓库（存放 Markdown 与配置）

  • 新建仓库（例如命名为 hexo-source）
  • 进入仓库设置：Settings → Secrets and variables → Actions → New repository secret
  • 添加一个名为 HEXO_DEPLOY_KEY 的密钥，值为私钥 id_rsa 的内容（用记事本打开复制）

仓库 2：发布仓库（存放静态文件，用于 GitHub Pages）

  • 仓库名必须为 <你的 GitHub 用户名>.github.io（固定格式，否则 GitHub Pages 无法生效）
  • 权限需设为公开，并开启 Discussions 功能（进入仓库设置 → Features 勾选）
  • 配置部署密钥：Settings → Deploy keys → Add deploy key
    • Title 填 HEXO_DEPLOY_PUB
    • Key 填入公钥 id_rsa.pub 的内容，并勾选 Allow write access（允许推送权限）

3. 配置 Hexo 环境文件

在源码仓库中创建 _hexo 目录，放入以下核心文件（可从本地 Hexo 环境中复制, 参考Hexo-博客配置）：

  • _config.yml：Hexo 主配置（需修改部署相关配置，见步骤 4）
  • _config.next.yml：NexT 主题配置（其他主题同理）
  • package.json：依赖配置（需包含 hexo、hexo-deployer-git 等核心依赖）
  • scaffolds/：文章模板（draft.md/page.md/post.md）
  • 静态资源：如头像（avatar.jpg）、关于页（about.md）等，按实际需求存放

4. 配置部署与工作流文件

① Hexo 部署配置（_hexo/_config.yml）

在配置文件中添加部署规则，指向发布仓库：

1
2
3
4
5
6
7
8
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  - type: git
    repo: git@github.com:<username>/<username>.github.io.git
    branch: master
    name: <username>
    email: <email>

② GitHub Actions 工作流（.github/workflows/hexo-deploy.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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
name: hexo-deploy  # 工作流名称

# 触发条件：向 master 分支推送时执行
on:
  push:
    branches: ["master"]
    
jobs:
  build:
    runs-on: ubuntu-latest  # 使用 Ubuntu 环境
    steps:
      # 1. 配置时区（避免时间显示异常）
      - name: Setup Timezone
        uses: szenius/set-timezone@v2.0
        with:
          timezoneLinux: "Asia/Shanghai"
      
      # 2. 拉取源码仓库内容到 source/_posts
      - uses: actions/checkout@v3
        with:
          path: source/_posts
      
      # 3. 安装 Node.js（需与本地开发环境版本一致，这里用 20.x）
      - name: Use Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      # 4. 缓存 NPM 依赖（加速构建）
      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      
      # 5. 配置 SSH 密钥（用于向发布仓库推送）
      - name: Setup Git
        env:
          ACTION_DEPLOY_KEY: ${{ secrets.HEXO_DEPLOY_KEY }}  # 引用源码仓库的私钥
        run: |
          mkdir -p ~/.ssh/
          echo "$ACTION_DEPLOY_KEY" > ~/.ssh/id_rsa
          chmod 700 ~/.ssh
          chmod 600 ~/.ssh/id_rsa  # 严格权限，否则 SSH 会拒绝使用
          ssh-keyscan github.com >> ~/.ssh/known_hosts  # 信任 GitHub 主机
      
      # 6. 拉取主题（以 NexT 为例，其他主题修改仓库地址即可）
      - name: Use Themes
        uses: actions/checkout@v3
        with:
          repository: next-theme/hexo-theme-next
          path: themes/next
      
      # 7. 还原 Hexo 环境（从 _hexo 目录复制配置文件）
      - name: Setup Hexo
        run: |
          npm install -g hexo-cli  # 全局安装 Hexo 命令行工具
          # 复制核心配置文件
          cp source/_posts/_hexo/_config.yml .
          cp source/_posts/_hexo/_config.next.yml .
          cp source/_posts/_hexo/package.json .
          # 复制文章模板
          mkdir scaffolds
          cp source/_posts/_hexo/scaffolds/* scaffolds/
          # 复制静态页面（关于页、分类页等，按实际需求调整）
          mkdir -p source/about source/categories source/tags source/images
          cp source/_posts/_hexo/about.md source/about/index.md
          cp source/_posts/_hexo/categories.md source/categories/index.md
          cp source/_posts/_hexo/tags.md source/tags/index.md
          cp source/_posts/_hexo/*.jpg source/images/  # 复制图片资源
          # 安装依赖
          npm install
      
      # 8. 缓存部署目录（加速后续构建）
      - name: Cache Deploy
        uses: actions/cache@v4
        with:
          path: .deploy_git
          key: ${{ runner.OS }}-deploy-cache
          restore-keys: |
            ${{ runner.OS }}-deploy-cache
      
      # 9. 构建并发布
      - name: Deploy
        run: |
          cd .deploy_git && git pull  # 拉取最新发布内容，避免冲突
          cd ..
          hexo clean  # 清理缓存
          hexo generate  # 生成静态文件
          hexo deploy  # 部署到发布仓库

验证与使用

  1. 将上述文件提交到源码仓库的 master 分支，GitHub Actions 会自动触发工作流；
  2. 进入源码仓库的 Actions 标签页，查看工作流执行状态，若显示绿色对勾则部署成功；
  3. 访问 https://<你的用户名>.github.io，即可看到最新发布的博客。

注意事项

  1. 私钥 HEXO_DEPLOY_KEY 是敏感信息，切勿泄露或提交到仓库；
  2. 发布仓库名必须严格为 <用户名>.github.io，否则 GitHub Pages 无法正常访问；
  3. 若主题是自定义修改过的，建议将主题 fork 到自己的仓库，再在工作流中拉取自己的 fork 版本；
  4. 本地预览时，可在源码仓库中手动搭建 Hexo 环境（复制 _hexo 目录文件，执行 hexo server）。

参考

Hexo官方提供的Github Actions部署示例

0%