Hexo + GitHub Pages 搭建个人博客：从零到自动部署

🚀 Hexo + GitHub Pages 自动化静态博客搭建全攻略

与之前的 Hexo+Github+Cloudflare Pages方案 不同，本方案将使用 GitHub 自带的 GitHub Actions 功能，同样能实现“本地只管 git push，云端自动编译上线”的完全自动化流程，非常适合希望将源码和静态网页都完整保留在 GitHub 上的同学。

本教程将带你从零开始，使用 Node.js 和 Git 在 Windows 环境下配置 Hexo 博客，并利用 GitHub Actions 实现“本地一键推送源码，云端自动编译并发布至 GitHub Pages”的终极无缝托管。

---

🛠️ 一、准备工作（与前面的方案一样是环境安装）

1. 安装 Node.js

Hexo 是基于 Node.js 运行的静态博客框架。

• 下载： 访问 Node.js 官网，下载并安装 LTS（长期支持版）。
• 验证： 打开电脑的 PowerShell，输入以下命令，看到版本号即代表成功：

node -v
npm -v

📷
📷

2. 安装 Git

Git 用于管理你的博客源码并推送到 GitHub。

• 下载： 访问 Git 官网 下载并安装。
• 配置初始信息：（必须配置，否则无法提交代码）

git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"
# 关闭 Windows 换行符的烦人警告
git config --global core.safecrlf false

📷

---

🏗️ 二、本地初始化 Hexo 博客

1. 创建一个空文件夹（例如 D:\closeblog）。
2. 在该文件夹内空白处右键，选择 “在终端中打开”（PowerShell）：

cd D:\closeblog

3. 全局安装 Hexo 命令行工具：

npm install -g hexo-cli

4. 初始化 Hexo 模板并安装依赖：（点后面的 . 代表在当前文件夹直接生成）

# 在当前文件夹生成博客项目
hexo init . 
# 安装项目所需依赖
npm install

执行完成后，目录中会出现几个重要文件和文件夹：

名称	用途
_config.yml	Hexo 的主要配置文件
source/_posts	存放 Markdown 文章
themes	存放主题
package.json	记录项目依赖和构建命令
public	执行构建后生成的静态网页

📷

💡 本地预览： 此时输入 hexo s，并在浏览器打开 http://localhost:4000，即可看到你的 Hexo 博客。在终端按 Ctrl + C 可停止预览。
📷

---

🔐 三、配置 GitHub 专属双分支仓库

为了既能保护你的 Hexo 源码，又能展示公开的静态网页，我们将使用一个仓库的 “双分支” 策略：

• main 分支： 存放你的 Hexo 博客源码（包括各种配置、Markdown 文本），这里免费GitHub用户只能选择 Public 公开仓库，不能选择 Private 私有仓库。
• gh-pages 分支（公开/自动生成）： 专门存放编译后的 HTML 静态文件，供 GitHub Pages 渲染展示。

1. 建立 GitHub 仓库

登录 GitHub，选择 New repository。本文使用 GitHub Pages 的“用户站点”模式。假设你的 GitHub 用户名是 example，那么按下面的方式填写：

• Repository name：你的用户名.github.io；
• Visibility：选择 Public；这里免费GitHub用户不能使用Private(私有)仓库部署GitHub Pages。
• README、.gitignore 和 License 暂时都不要勾选。

仓库名必须与 GitHub 用户名完全一致。例如用户名是 example，仓库名必须是 example.github.io。

📷
注：这样命名后，你未来的博客网址就会是极其简短的 [https://你的用户名.github.io](https://你的用户名.github.io)。

创建完成后先不要关闭页面，接下来需要使用仓库的 HTTPS 地址。

📷

站点仓库和普通项目仓库的地址不同、命名方式也是不同的

📷

如果是普通的项目仓库，命名方式如下面所示：

📷

📷

点击 Create repository创建仓库。

2.本地写博客文章

在博客根目录执行：

hexo new "我的第一篇文章" 或 hexo n "我的第一篇文章"

Hexo 会在 source\_posts 中创建一个 Markdown 文件。打开后可以看到类似下面的文章信息：

---
title: 我的第一篇文章
date: 2026-07-28 10:00:00
tags:
---

在第二个 --- 下方编写正文，保存后再次运行：

hexo server 或 hexo s

刷新浏览器，就能看到新文章。此时文章只存在于本地电脑端，GitHub仓库还没有内容。

3. 本地源码首次推送

还是在博客根目录（D:\closeblog）下依次执行：

git init
git add .
git commit -m "我的第次上传"
git branch -M main

# 绑定远程仓库（将下面链接换成你从 GitHub 复制来的 HTTPS 链接）
git remote add origin https://github.com/你的用户名/你的仓库名.github.io.git

# 首次推送（会弹出浏览器进行登录授权）
![authorize.png](https://img.didadi.xyz/file/1785233716237_authorize.png)
![authorize-gemingong.png](https://img.didadi.xyz/file/1785233719353_authorize-gemingong.png)
git push -u origin main

稍等片刻，GitHub仓库就显示出了内容。

🤖 四、配置 GitHub Actions 云端自动构建

我们需要让 GitHub 收到源码后，自动在云端帮我们执行 hexo generate 并把生成的网页放到 GitHub Pages 中。

1. 配置 GitHub 仓库的写入权限（非常关键）

由于自动化脚本需要把生成的网页写回你的仓库，必须放开权限：

1. 打开你的 GitHub 仓库页面，点击顶部的 Settings（设置）。
2. 在左侧菜单栏找到 Actions -> 点击 General。
3. 滚动到最下方找到 Workflow permissions，将默认的 Read 选项改为 “Read and write permissions”（读写权限）。
4. 点击 Save 保存。
   
   

2. 创建自动化脚本文件

1. 在本地博客根目录（如D:\closeblog）下，新建一个名为 .github 的文件夹。
2. 在 .github 内部再建一个名为 workflows 的文件夹。
   
3. 在 workflows 文件夹内，用 Notepad++ 新建一个名为 deploy.yml 的文件，并将以下内容完整复制进去并保存：

name: Deploy Hexo Blog

on:
  push:
    branches:
      - main # 当检测到 main 分支有代码推送时触发

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24' # 这里的 Node 版本保持与你本地一致

      - name: Install dependencies
        run: |
          npm ci

      - name: Build static files
        run: |
          npx hexo generate

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: public # 将 hexo 生成的 public 文件夹推送到 gh-pages 分支
          branch: gh-pages 

3. 推送脚本激活云端构建

在本地终端执行日常三部曲，把这个脚本送上云端：

git add .
git commit -m "添加自动化部署脚本"
git push

此时前往 GitHub 仓库的 Actions 标签页，你会看到一个绿色的圈圈在转动，说明 GitHub 已经在云端帮你编译博客了。编译完成后，你的仓库会自动多出一个 gh-pages 分支。

🌐 五、开启 GitHub Pages 服务

1. 编译成功后，点击仓库顶部的 Settings -> 左侧菜单栏点击 Pages。
2. 在 Build and deployment 下方的 Source 保持为 Deploy from a branch。
3. Branch（分支） 选择 gh-pages，后面的目录选择 / (root)。
4. 点击 Save。

🎉 大功告成！ 页面顶部马上会隆重出现一行网址：Your site is live at https://...。点击它，属于你的 GitHub Pages 个人博客就正式全网公开上线了！

🎉 这时也可以使用 https://你的用户名.github.io 这个系统分配的默认域名进行访问了。

📅 六、日常写博客与更新流程

以后写新博客或修改样式，完全不需要在本地管什么 hexo g 或 hexo d，直接老规矩“三部曲”：

git add .
git commit -m "发表了一篇新文章"
git push

自动运行逻辑： 本地代码一推送到 main 分支 ➔ GitHub Actions 收到信号在云端自动用 Node.js 编译出静态文件 ➔ 自动塞进 gh-pages 分支 ➔ GitHub Pages 网站瞬间完成自动更新！

如果更换电脑写作的话，设置方式同上一篇博客的内容： Hexo+Github+Cloudflare Pages方案

🔧 七、修改配置文件_config .yml，设置博客地址

对于站点仓库，博客地址是 https://example.github.io。

打开博客根目录中的 _config.yml，找到 url 和 root，修改为：

url: https://你的用户名.github.io
root: /

例如 GitHub 用户名为 example：

url: https://example.github.io
root: /

YAML 对空格和缩进比较敏感，冒号后要保留一个空格，也不要使用中文冒号。

如果你使用的是普通项目仓库

普通项目仓库的网址通常会多一层仓库名。例如仓库叫 example，配置应改为：

url: https://你的用户名.github.io/example
root: /example/

如果漏掉这里的 /example/，常见现象是首页能够打开，但 CSS、图片和文章链接全部变成 404。第一次建博客时，建议直接使用 用户名.github.io 仓库，能少处理一层路径问题,这也是为什么建议注册GitHub时选好用户名的原因。虽然注册后也可以修改用户名，但修改之后容易出现一些问题。

📷

🛠️ 八、常用命令

以后更新博客，不需要重新配置 GitHub Pages。日常流程可以简化为四步。

1. 创建文章

hexo new "文章标题"

2. 本地预览

hexo server

3. 查看本次修改

git status

4. 提交并推送

git add .
git commit -m "发布：文章标题"
git push

推送完成后，GitHub Actions 会自动重新构建和发布。建议每次都到 Actions 页面确认任务变成绿色，不要只看到 git push 成功就认为网站已经更新。

🌐 九、绑定独立域名（可选）

github.io 地址可以长期使用，但如果准备认真维护博客，建议绑定自己持有的独立域名。这样以后即使从 GitHub Pages 迁移到 Cloudflare Pages 或 VPS，仍然可以通过原域名访问。

进入：

Settings → Pages → Custom domain

填写域名，例如 www.example.com。如果使用 www 子域名，通常需要在域名的 DNS 管理页面添加一条 CNAME 记录：

类型：CNAME
名称：www
目标：你的用户名.github.io

DNS 生效后，回到 GitHub Pages 设置页面完成域名检查，并开启 Enforce HTTPS。

同时把 Hexo 的 _config.yml 修改为：

url: https://www.example.com
root: /

保存后重新提交并推送，让所有文章链接和资源地址使用新域名。

📷【截图待补 10：Custom domain 检查成功，并开启 Enforce HTTPS】

⚠️ 十、常见问题排查

1. npm ci 执行失败

先确认仓库中存在 package-lock.json。如果锁文件缺失或与依赖不一致，在本地执行：

npm install
npm run build

确认本地构建成功后，把更新后的 package-lock.json 一起提交。

2. 网站能打开，但没有样式

这通常是 url 或 root 配置错误。

用户站点应为：

url: https://你的用户名.github.io
root: /

普通项目站点则需要把仓库名写进路径。修改后执行：

npx hexo clean
npm run build
git add .
git commit -m "修复站点路径"
git push

3. Actions 提示 Pages 权限不足

检查三项内容：

• Settings → Pages 中的 Source 是否为 GitHub Actions；
• 工作流是否包含 pages: write；
• 工作流是否包含 id-token: write。

4. 推送成功，但网站内容没有更新

依次检查：

1. 推送的分支是不是 main；
2. Actions 工作流是否成功；
3. 浏览器是否仍在使用缓存；
4. 文章是否放在 source/_posts；

5. 仓库里没有 gh-pages 分支，正常吗

正常。本文使用 GitHub 官方 Pages artifact 方式发布，不需要创建或维护 gh-pages 分支。生成的静态网页会作为部署产物交给 GitHub Pages，源码仍然保存在 main 分支。

6. 有时 Actions 报错，有可能是语法不对，或者部署文件中缺少内容，如果缺少 themes 主题文件等。

📝 总结

这套方案的核心并不复杂：Hexo 负责生成网页，GitHub 负责保存源码，GitHub Actions 负责自动构建，GitHub Pages 负责对外发布。

第一次配置步骤稍多，但完成之后，日常维护只剩下写作、预览、提交和推送。对于以文章为主的个人博客，它既节省服务器成本，也能保留完整的版本记录。

如果你更在意源码私密、分支预览或 Cloudflare DNS 集成，可以进一步比较 Cloudflare Pages；如果以后需要后端程序、数据库或完整的服务器控制权，再考虑迁移到 VPS + Nginx。