王彦坤 Hexo https://wangyankun.github.io/ All rights reserved 2026, 王彦坤 记录想法，写写日记 王彦坤的博客 2026-05-05T12:43:40.381Z 王彦坤

项目周期: 2026-04-27 ~ 2026-05-05
技术栈: Hexo + NexT 主题 + GitHub Pages + GitHub Actions
仓库: https://github.com/WangYankun/WangYankun.github.io
线上地址: https://wangyankun.github.io
项目状态: ✅ 已完成

一、项目概述

搭建个人博客「坤的博客」，实现以下目标：

  • 📝 Hexo 静态博客框架，NexT 主题（Muse 风格）
  • 🚀 GitHub Actions 自动构建部署（GitHub Pages）
  • 💬 Giscus 评论系统（基于 GitHub Discussions）
  • 📱 响应式设计，适配移动端
  • 🔍 本地搜索、RSS 订阅、代码高亮
  • 📊 后台 CMS 支持手机/电脑端写作发布
  • 🇨🇳 适配国内网络环境（系统字体、百度统计等）

二、完整搭建步骤

2.1 本地环境准备

1
2
3
4
5
6
7
8
9
10
# 1. 安装 Node.js（建议 v22+）
node -v  # 确认版本 >= 22

# 2. 安装 Hexo CLI
npm install -g hexo-cli

# 3. 初始化博客（如果从零开始）
hexo init blog-build
cd blog-build
npm install

2.2 主题安装

1
2
# 安装 NexT 主题（推荐最新稳定版）
npm install hexo-theme-next

在 _config.yml 中启用：

1
theme: next

2.3 GitHub 仓库配置（双分支方案）

仓库结构：

  • source 分支 — 博客源码（_config.yml、主题配置、scripts、文章草稿等）
  • main 分支 — 文章（source/_posts、source/uploads）+ CMS 发布的内容
1
2
3
4
5
6
7
8
9
# 初始化 git
git init
git checkout -b source

# 配置远程仓库
git remote add origin https://github.com/WangYankun/Wangyankun.github.io.git
git add .
git commit -m "Initial blog setup"
git push -u origin source

2.4 GitHub Actions 工作流

创建 .github/workflows/deploy.yml（放在 source 分支）：

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
name: Deploy Blog to GitHub Pages

on:
  push:
    branches: [source, main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source branch
        uses: actions/checkout@v4
        with:
          ref: source

      - name: Checkout main for posts
        uses: actions/checkout@v4
        with:
          ref: main
          path: _main
          sparse-checkout: |
            source/_posts
            source/uploads

      - name: Merge posts from main
        run: |
          rm -rf source/_posts source/uploads
          mkdir -p source
          cp -r _main/source/_posts source/ 2>/dev/null || true
          cp -r _main/source/uploads source/ 2>/dev/null || true
          rm -rf _main

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install Dependencies
        run: |
          npm ci
          npm install hexo-generator-feed hexo-deployer-git hexo-generator-search --save

      - name: Build
        run: npx hexo generate

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

GitHub Pages 设置：

  • Settings → Pages → Source → GitHub Actions

2.5 NexT 主题配置（_config.next.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
# 主题风格
scheme: Muse
darkmode: true

# 字体（使用系统字体，适配国内网络）
font:
  enable: true
  global:
    external: false
    family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif

# 代码块
codeblock:
  theme:
    light: default
    dark: atom-one-dark
  style: flat
  copy_button:
    enable: true
    show_result: true

# 搜索
local_search:
  enable: true
  trigger: auto

# RSS
feed:
  enable: true
  type:
    - atom
    - rss2

# 社交链接
social:
  GitHub: https://github.com/WangYankun || fab fa-github
  E-Mail: mailto:yourname@example.com || fa fa-envelope
  RSS: /atom.xml || fa fa-rss

# 自定义样式
custom_file_path:
  style: source/_data/styles.styl

2.6 Giscus 评论系统集成

步骤 1：创建 Discussion 仓库

在 GitHub 创建 WangYankun/blog-comments 仓库（必须公开），开启 Discussions 功能。

步骤 2：获取配置参数

访问 https://giscus.app/zh-CN，按提示获取：

  • repo: WangYankun/blog-comments
  • repo_id: （自动生成）
  • category: Announcements
  • category_id: （自动生成）

步骤 3：添加 giscus 注入脚本

创建 scripts/giscus-inject.js：

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
/* global hexo */
'use strict';

hexo.extend.filter.register('theme_inject', function(injects) {
  const giscusConfig = hexo.theme.config.giscus;
  if (giscusConfig && giscusConfig.enable) {
    injects.comment.raw('giscus', `
      <div class="comments giscus-container">
        <script src="https://giscus.app/client.js"
          data-repo="${giscusConfig.repo}"
          data-repo-id="${giscusConfig.repo_id}"
          data-category="${giscusConfig.category}"
          data-category-id="${giscusConfig.category_id}"
          data-mapping="${giscusConfig.mapping}"
          data-strict="${giscusConfig.strict}"
          data-reactions-enabled="${giscusConfig.reactions_enabled}"
          data-emit-metadata="${giscusConfig.emit_metadata}"
          data-input-position="${giscusConfig.input_position}"
          data-theme="preferred_color_scheme"
          data-lang="${giscusConfig.lang}"
          data-loading="${giscusConfig.loading}"
          crossorigin="anonymous"
          async>
        </script>
      </div>
    `, {}, { cache: true });

    if (!hexo.theme.config.comments.active) {
      hexo.theme.config.comments.active = 'giscus';
      hexo.theme.config.comments.activeClass = 'giscus';
    }
  }
});

步骤 4：在 _config.next.yml 中添加 giscus 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
giscus:
  enable: true
  repo: WangYankun/blog-comments
  repo_id: R_kgDOSOAn3A        # 替换为你的 repo_id
  category: Announcements
  category_id: DIC_kwDOSOAn3M4C7zhm  # 替换为你的 category_id
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: bottom
  theme:
    light: light
    dark: dark_dimmed
  lang: zh-CN
  loading: lazy

步骤 5：部署

1
2
3
4
5
6
7
8
9
cd blog-build

# 生成
npx hexo clean && npx hexo generate

# 提交源码到 source 分支（不要使用 hexo d！）
git add _config.next.yml scripts/giscus-inject.js
git commit -m "feat: add giscus comment support"
git push origin source

2.7 日常发布流程

方式一：本地写文章

1
2
3
4
5
6
7
8
9
10
11
12
# 创建新文章
npx hexo new post "文章标题"

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

# 本地预览
npx hexo server

# 提交到 source 分支
git add source/_posts/文章标题.md
git commit -m "feat: 发布文章「文章标题」"
git push origin source

方式二：通过管理后台发布

  1. 本地启动 CMS：npx hexo server
  2. 访问 http://localhost:4000/admin
  3. 编辑/发布文章
  4. 提交变更到 source 分支并推送
  5. 同时推送 main 分支（触发 GitHub Actions 构建）

方式三：手机端写作（未来规划）

通过管理后台 + MinIO 文件同步，实现移动端 CMS 写作。

三、踩坑记录

🕳️ 坑 1：NexT 主题不支持 giscus

现象: 在 _config.next.yml 配置了 giscus，但文章页没有评论区。

原因: NexT 8.x 版本没有内置 giscus 支持。配置项写了也不会渲染。

解决: 通过 NexT 的 theme_inject 机制，编写自定义脚本 scripts/giscus-inject.js，手动注入 giscus 脚本。

🕳️ 坑 2：hexo d 推错了分支

现象: 博客首页 404。

原因: hexo d 把完整的 public/ 静态文件推到了 main 分支。但 GitHub Actions 工作流期望 main 分支只包含 source/_posts 和 source/uploads。预构建文件覆盖了原有结构，导致 Actions 构建出来的页面为空。

解决:

  1. 在 GitHub 上 revert 那个 commit，恢复 main 分支
  2. 以后不要用 hexo d — 改用 GitHub Actions 自动部署
  3. 只 push 源码到 source 分支，Actions 自动构建

🕳️ 坑 3：_config.yml 的 deploy 占位符

现象: hexo d 推到了 username/username.github.io 而不是自己的仓库。

原因: 初始配置是占位符：

1
2
deploy:
  repo: https://github.com/username/username.github.io.git

解决: 改为自己的仓库地址：

1
2
deploy:
  repo: https://github.com/WangYankun/Wangyankun.github.io.git

🕳️ 坑 4：_config.yml 的 url 占位符

现象: 生成的 HTML 中链接指向 https://username.github.io。

解决: 改为自己的地址：

1
url: https://Wangyankun.github.io

🕳️ 坑 5：评论提交失败 — CORS / loopback address space

现象: 评论区显示正常，点击提交时报 ERR_FAILED，console 报 CORS 错误。

原因: 本地开启了网络加速/代理工具，导致 GitHub API 请求被路由到 loopback 地址，Chrome 的安全策略拦截了该请求。

解决: 关闭网络加速工具后再访问。

🕳️ 坑 6：首页看不到评论区

现象: 以为 giscus 没生效，因为首页没有评论区。

原因: NexT 主题的评论组件只在文章页显示，首页不显示。这是正常行为。

解决: 进入具体文章页面查看评论区。

🕳️ 坑 7：push 到 source 分支不触发 Actions

现象: push 到 source 分支后，GitHub Actions 没有自动运行。

原因: 工作流配置了 branches: [source, main] 但实际部署需要两个分支都有更新（source 需要 main 的文章）。

解决: push 到 main 分支（如管理后台发布文章）会触发 Actions。如果只改了 source 分支的配置，也需要 push 一下 main 触发。

四、关键文件清单

文件位置作用
_config.yml项目根目录Hexo 核心配置
_config.next.yml项目根目录NexT 主题配置
scripts/giscus-inject.js项目根目录Giscus 评论注入脚本
source/_data/styles.styl自定义样式自定义 CSS
.github/workflows/deploy.ymlsource 分支GitHub Actions 工作流
source/_posts/source 分支文章（本地写作）
source/_posts/main 分支文章（CMS 发布 + Actions 合并）
source/uploads/main 分支上传的图片

五、经验总结

  1. 理解工作流再操作 — 在搞清楚 GitHub Actions 的构建逻辑之前，不要盲目执行 hexo d
  2. 双分支架构的好处 — source 分支管代码，main 分支管文章，职责清晰。但需要严格遵守操作规范
  3. NexT 的 inject 机制 — 对于不支持的功能，可以通过 scripts/*.js 注入自定义代码
  4. 网络工具的影响 — 开发/测试时注意关闭代理，避免引入难以排查的网络问题
  5. 配置项占位符 — 初始化配置中的 username、占位符等，第一时间替换为真实值
]]> https://wangyankun.github.io/2026/05/05/%E4%B8%AA%E4%BA%BA%E5%8D%9A%E5%AE%A2%E6%90%AD%E5%BB%BA%E9%A1%B9%E7%9B%AE%E6%80%BB%E7%BB%93/ 2026-05-05T12:14:00.000Z

项目周期: 2026-04-27 ~ 2026-05-05
技术栈: Hexo + NexT 主题 + GitHub Pages + GitHub Actions
仓库: https://github.com/WangYankun/WangYankun.github.io
线上地址: https://wangyankun.github.io
项目状态: ✅ 已完成

一、项目概述

搭建个人博客「坤的博客」，实现以下目标：

  • 📝 Hexo 静态博客框架，NexT 主题（Muse 风格）
  • 🚀 GitHub Actions 自动构建部署（GitHub Pages）
  • 💬 Giscus 评论系统（基于 GitHub Discussions）
  • 📱 响应式设计，适配移动端
  • 🔍 本地搜索、RSS 订阅、代码高亮
  • 📊 后台 CMS 支持手机/电脑端写作发布
  • 🇨🇳 适配国内网络环境（系统字体、百度统计等）

二、完整搭建步骤

]]> 个人博客搭建项目总结 2026-05-05T12:43:40.381Z 王彦坤 为什么要支持手机？

既然是个人博客，就是要记录日常的点点滴滴，而手机正是这样一个最好用的入口

用什么格式写文章？

测试下来，还是markdown 最好用，因为手机最大的短板是无法选中调格式，md 很好的解决了这个问题

评论功能是否必须？

我觉得还是有必要的，至少有一个与外界交流的窗口

最后

算了，不折腾了，评论功能一直搞不定。HiClaw 真垃圾。。

]]> https://wangyankun.github.io/2026/05/04/%E8%BF%99%E6%98%AF%E6%88%91%E7%94%A8%E6%89%8B%E6%9C%BA%E5%8F%91%E7%9A%84%E5%8D%9A%E5%AE%A2/ 2026-05-04T14:29:00.000Z 为什么要支持手机？

既然是个人博客，就是要记录日常的点点滴滴，而手机正是这样一个最好用的入口

<]]> 这是我用手机发的博客 2026-05-05T12:43:40.381Z 王彦坤 你好，世界！

这是我的个人博客的第一篇文章。

搭建这个博客的初衷很简单 —— 想要一个属于自己的地方，记录想法、分享笔记、写写日记。

为什么选择 Hexo？

在选择博客框架的时候，我考虑了几个方案：

  1. WordPress

     — 功能强大，但太重了

  2. Hugo

     — 构建速度快，但主题生态不如 Hexo

  3. Hexo

     — Node.js 生态，主题丰富，中文社区活跃 ✅

最终选择了 Hexo + NexT 主题，配合 GitHub Pages 免费部署。

博客特性

  • ✅ 响应式设计，手机/平板/电脑都能看
  • ✅ 深色模式支持
  • ✅ 评论系统（Giscus）
  • ✅ RSS 订阅
  • ✅ 代码高亮
  • ✅ 站内搜索

写在最后

以后会在这里记录一些想法和技术笔记，欢迎大家常来逛逛。

2026年4月27日，于博客诞生之日

]]> https://wangyankun.github.io/2026/05/04/%E6%B5%8B%E8%AF%95%EF%BC%9A%E9%80%9A%E8%BF%87%E7%AE%A1%E7%90%86%E5%90%8E%E5%8F%B0%E5%8F%91%E5%B8%83%E7%AC%AC%E4%B8%80%E7%AF%87%E5%8D%9A%E5%AE%A2/ 2026-05-04T09:33:00.000Z 你好，世界！

这是我的个人博客的第一篇文章。

搭建这个博客的初衷很简单 —— 想要一个属于自己的地方，记录想]]>

我的第一篇博客 2026-05-05T12:43:40.381Z