个人博客搭建项目总结

发表于 2026-05-05 分类于项目总结

项目周期: 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. 安装 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 发布的内容

# 初始化 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 分支）：

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）

核心配置项：

# 主题风格
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：

/* 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 配置

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：部署

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 日常发布流程

方式一：本地写文章

# 创建新文章
npx hexo new post "文章标题"

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

# 本地预览
npx hexo server

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

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

本地启动 CMS：npx hexo server
访问 http://localhost:4000/admin
编辑/发布文章
提交变更到 source 分支并推送
同时推送 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 构建出来的页面为空。

解决:

在 GitHub 上 revert 那个 commit，恢复 main 分支
以后不要用 hexo d — 改用 GitHub Actions 自动部署
只 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.yml`	source 分支	GitHub Actions 工作流
`source/_posts/`	source 分支	文章（本地写作）
`source/_posts/`	main 分支	文章（CMS 发布 + Actions 合并）
`source/uploads/`	main 分支	上传的图片

五、经验总结

理解工作流再操作 — 在搞清楚 GitHub Actions 的构建逻辑之前，不要盲目执行 hexo d
双分支架构的好处 — source 分支管代码，main 分支管文章，职责清晰。但需要严格遵守操作规范
NexT 的 inject 机制 — 对于不支持的功能，可以通过 scripts/*.js 注入自定义代码
网络工具的影响 — 开发/测试时注意关闭代理，避免引入难以排查的网络问题
配置项占位符 — 初始化配置中的 username、占位符等，第一时间替换为真实值