使用 Hexo + Fluid 搭建个人博客并托管到 GitHub Pages

1. 环境准备

需要提前安装以下工具：

Node.js（建议 v16+）：参考菜鸟教程安装
Git：参考菜鸟教程完成安装与配置，注册github账户

验证安装：

1
2
3

node -v
npm -v
git --version

2. 安装 Hexo

参考Hexo安装官方文档

1	npm install -g hexo-cli

linux可以运行以下命令，可以直接使用hexo [command],否则需要使用npm hexo [command]

1	echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile

创建博客项目：

1
2
3

hexo init my-blog
cd my-blog
npm install

此时目录结构如下：

my-blog/
├── _config.yml          # Hexo 主配置
├── package.json
├── scaffolds/           # 模板（post, page, draft）
├── source/
│   └── _posts/          # 博客文章（Markdown）
└── themes/              # 主题目录

启动本地预览：

1	npx hexo server

浏览器打开 http://localhost:4000 即可看到默认页面。

3. 安装 Fluid 主题

更多其他主题可以在themes里找到

方式一：npm 安装（推荐）

1	npm install hexo-theme-fluid

方式二：直接下载（本blog使用这种方法）

从 Fluid GitHub Releases 下载最新版本，解压到 themes/fluid 目录。

启用主题

编辑根目录 _config.yml，修改 theme 字段：

1	theme: fluid

创建主题配置文件（覆盖主题默认配置，不需要修改 themes/fluid 内的文件）：

1	cp themes/fluid/_config.yml _config.fluid.yml

如果是 npm 安装的，从 node_modules/hexo-theme-fluid/_config.yml 复制。

重新启动 npx hexo server，就能看到 Fluid 主题的页面了。

4. 基础配置

4.1 站点配置（`_config.yml`）

title: My Blog            # 站点标题
subtitle: ''
description: ''
author: YourName
language: zh-CN            # 语言，en 或 zh-CN
timezone: Asia/Shanghai
url: https://yourusername.github.io   # 部署后的访问地址

4.2 主题配置（`_config.fluid.yml`）

常用的配置项：

# 导航栏标题
navbar:
  blog_title: "My Blog"

# 首页 Banner
index:
  banner_img: /img/banner.jpg
  slogan:
    enable: true
    text: "Welcome to My Blog"

# 文章页
post:
  banner_img: /img/default.png

# 关于页
about:
  enable: true
  avatar: /img/avatar.jpg
  name: "YourName"
  intro: "A short introduction"

更多配置项参考：Fluid 配置指南

5. 写文章

创建新文章

1	npx hexo new "My First Post"

会在 source/_posts/ 下生成 My-First-Post.md，编辑其内容：

---
title: My First Post
date: 2026-03-21 16:00:00
tags: [Tag1, Tag2]
index_img: /img/cover.jpg       # 首页封面图
banner_img: /img/banner.jpg     # 文章页顶部大图
---

正文内容，支持标准 Markdown 语法。

## 二级标题

- 列表项
- 列表项

```python
print("Hello World")
```

常用 Front-matter 字段

字段	说明
`title`	文章标题
`date`	发布日期
`tags`	标签列表
`index_img`	首页封面图
`banner_img`	文章页顶部大图
`sticky`	置顶优先级，数字越大越靠前
`hide`	设为 true 则全站隐藏
`archive`	设为 false 则仅在首页隐藏

创建草稿

1	npx hexo new draft "Draft Title"

草稿存放在 source/_drafts/，不会被发布。想发布时：

1	npx hexo publish "Draft Title"

6. 创建标签页、关于页等

1 2	npx hexo new page tags npx hexo new page about

编辑生成的 source/tags/index.md：

---
title: Tags
layout: tags
---

编辑 source/about/index.md：

---
title: About
layout: about
---

在这里写关于页的内容。

7. 部署到 GitHub Pages

参考Hexo官方github配置文档

7.1 创建 GitHub 仓库

在 GitHub 上创建一个仓库，命名为 yourusername.github.io（替换为你的 GitHub 用户名）。

7.2 初始化 Git 并推送

cd my-blog
git init
git remote add origin git@github.com:yourusername/yourusername.github.io.git
git add -A
git commit -m "init: hexo blog with fluid theme"
git push -u origin master

7.3 配置 GitHub Actions 自动部署

在项目根目录创建 .github/workflows/pages.yml，将以下内容复制进去，注意，其中的Node的版本需要修改（下面的示例代码中是24.14.0），使用node -v查看，注意输出的是v24.14.0类似的格式，不要把v加上，会导致workflow无法工作

name: Pages

on:
  push:
    branches:
      - master # default branch

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          # If your repository depends on submodule, please see: https://github.com/actions/checkout
          submodules: recursive
      - name: Use Node.js 24.14.0
        uses: actions/setup-node@v4
        with:
          # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node
          # Ref: https://github.com/actions/setup-node#supported-version-syntax
          node-version: "24.14.0"
      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      - name: Install Dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

7.4 启用 GitHub Pages

进入仓库 Settings → Pages
Source 选择 GitHub Actions
推送代码后，Actions 会自动构建并部署

部署完成后访问 https://yourusername.github.io 即可看到博客。

8. 日常工作流

# 写新文章
npx hexo new "Article Title"

# 本地预览
npx hexo server

# 发布（推送到 GitHub 即自动部署）
git add -A
git commit -m "add: new article"
git push

常用命令速查

命令	说明
`npx hexo new "Title"`	新建文章
`npx hexo new page name`	新建页面
`npx hexo server`	本地预览（端口 4000）
`npx hexo generate`	生成静态文件到 `public/`
`npx hexo clean`	清除缓存和已生成文件