Hexo + GitHub Pages | 有手就行的博客搭建指南

About 1153 wordsAbout 4 min

2025-10-13

前言

在开始搭建博客之前，希望你对 Git 的基本操作有一定了解，并确保你的计算机上已经安装了以下软件：

Node.js（建议使用 LTS 版本）
Git

可通过以下命令检查是否安装：

node -v
npm -v
git --version

创建 Github 仓库

在 GitHub 上新建一个仓库，需要特别注意的是仓库名需要为 <your_github_username>.github.io 。

通过 GitHub Pages 部署

修改配置

修改仓库目录下的 _config.yml 中的 url ，将其更改为仓库地址：

url: https://<your_github_username>.github.io

通常，将 Hexo 生成的页面通过 GitHub Pages 挂载后，每次提交博客都需要使用 hexo clean && hexo generate && hexo deploy 命令来部署，比较繁琐。本文将介绍一种借助 GitHub Actions 来实现自动部署的方案，每当我们提交源代码到 GitHub 存放源码的分支上，便会启动工作流，自动将构建并将静态文件 push 到发布分支，实现部署。

在仓库目录下创建 .github/workflows/deploy.yml 文件，内容如下：

name: Hexo Deploy

on:
  push:
    branches: [main]

permissions:
  contents: write # 允许工作流写入仓库内容

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout # 检出代码
        uses: actions/checkout@v4

      - name: Update Submodule # 更新子模块
        run: |
          git submodule init
          git submodule update --remote

      - name: Setup Node.js # 设置Node.js环境
        uses: actions/setup-node@v4
        with:
          node-version: "22" # 指定Node.js版本（与本地一致）
          cache: "npm" # 启用 npm 缓存，减少重复下载

      - name: Install # 安装依赖
        run: |
          npm config set registry https://registry.npmmirror.com/
          npm cache clean --force
          npm install -g hexo-cli --registry=https://registry.npmmirror.com/
          npm install --registry=https://registry.npmmirror.com/

      - name: Build # 生成静态文件
        run: |
          hexo clean
          hexo generate

      - name: Deploy # 发布到gh-pages分支
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

启用 GitHub Pages

保存并提交所有更改到 main 分支：

git add .
git commit -m "chore: initial commit"
git push origin main

若进展顺利，GitHub Actions 会自动运行工作流，并将生成的静态文件推送到远程仓库的 gh-pages 分支。

在 GitHub 仓库页面，进入 Settings -> Pages ，在 Source 选项中选择 Deploy from a branch ，选择 gh-pages 分支 /(root) ，点击 Save 保存。

访问 https://<your_github_username>.github.io 即可看到你的博客上线了！

本地开发

在本地进行开发时，可以通过以下命令来创建一篇新文章或者新的页面：

hexo new [layout] <title>

同时开启本地服务器进行预览：

hexo server

编辑完成后，使用以下命令提交到源代码仓库：

git add .
git commit -m "<your commit message>"
git push origin main

Note

详细开发指南请参考Hexo 官方文档和主题用户手册。

在 GitHub Pages 上部署 Hexo

Hexo Fluid 用户手册

利用 GitHub Actions 自动部署 Hexo 博客

Copyright

License under:Attribution-NonCommercial-ShareAlike 4.0 International (CC-BY-NC-SA-4.0)

Hexo + GitHub Pages | 有手就行的博客搭建指南

前言

创建 Github 仓库

搭建 Hexo 博客框架

初始化 Hexo 项目

配置主题

本地部署

通过 GitHub Pages 部署

修改配置

添加工作流文件

启用 GitHub Pages

本地开发

Copyright