🌐 Hexo + GitHub Pages 搭建个人博客全流程指南（2024 最新版）

💡 本指南适用于 Windows/macOS/Linux，全程约 30 分钟，附关键避坑提示

🔑 一、前置准备

项目 要求 验证命令
GitHub 账号 注册地址 -
Node.js (LTS) ≥ 18.x node -v npm -v
Git ≥ 2.30 git --version
编辑器 VS Code / Typora 等 -

✅ 加速建议（国内用户）：

1
2
3
4
# 设置 npm 淘宝镜像
npm config set registry https://registry.npmmirror.com
# 可选：安装 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com

📦 二、安装与初始化 Hexo

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 全局安装 Hexo CLI
npm install -g hexo-cli

# 2. 创建博客目录（my-blog 可自定义）
hexo init my-blog
cd my-blog

# 3. 安装依赖（国内建议用 cnpm）
npm install  # 或 cnpm install

# 4. 本地预览（浏览器访问 http://localhost:4000）
hexo clean && hexo g && hexo s

✅ 出现 Hexo 默认欢迎页即成功！

🎨 三、个性化配置（关键步骤）

1️⃣ 基础配置（_config.yml）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 站点信息
title: 我的博客
subtitle: 记录成长
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

# URL（部署后修改为你的域名）
url: https://yourname.github.io
root: /

# 生成设置
permalink: :year/:month/:day/:title/
permalink_defaults:

2️⃣ 安装主题（以 Butterfly 为例）

1
2
3
4
5
6
7
# 进入 themes 目录
cd themes
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git butterfly
cd ../

# 修改 _config.yml
theme: butterfly

📌 主题配置：
复制 themes/butterfly/_config.yml.example 为 _config.butterfly.yml，按需修改（菜单、评论、SEO等）

3️⃣ 常用插件（按需安装）

1
2
3
npm install hexo-generator-searchdb --save    # 站内搜索
npm install hexo-wordcount --save            # 字数统计
npm install hexo-abbrlink --save             # 永久链接（避免中文路径问题）

📝 四、撰写与预览

1
2
3
4
5
# 创建新文章（自动在 source/_posts/ 生成 .md 文件）
hexo new "我的第一篇博客"

# 本地实时预览（修改后自动刷新）
hexo clean && hexo g && hexo s --debug

✨ 写作技巧：

  • 使用 Markdown 编辑（推荐 Typora/VS Code + Markdown 插件）
  • 图片建议存入 source/images/，引用相对路径
  • 文章 Front-matter 添加分类/标签：
    1
    2
    3
    4
    5
    6
    ---
    title: 示例
    date: 2024-02-26
    tags: [Hexo, 教程]
    categories: 技术
    ---

🚀 五、部署到 GitHub Pages（核心步骤）

1️⃣ 创建仓库

  • 仓库名必须为：你的GitHub用户名.github.io（如 zhangsan.github.io）
  • 选择 Public（免费用户私有仓库无法启用 Pages）

2️⃣ 配置 SSH 密钥（免密部署）

1
2
3
4
5
6
7
8
# 生成密钥（一路回车）
ssh-keygen -t ed25519 -C "your_email@example.com"

# 复制公钥内容
cat ~/.ssh/id_ed25519.pub  # Windows: type %USERPROFILE%\.ssh\id_ed25519.pub

# GitHub 操作：
# Settings → SSH and GPG keys → New SSH key → 粘贴公钥

✅ 测试连接：ssh -T git@github.com（看到 “Hi xxx! You’ve successfully authenticated” 即成功）

3️⃣ 配置部署（_config.yml 末尾）

1
2
3
4
deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io.git
  branch: main  # ⚠️ 重要：确认仓库默认分支名（新版 GitHub 为 main）

4️⃣ 安装部署插件 & 部署

1
2
npm install hexo-deployer-git --save
hexo clean && hexo g && hexo deploy

🌐 访问：https://你的用户名.github.io（首次部署需等待 2-5 分钟）

🌍 六、绑定自定义域名（可选但推荐）

  1. 购买域名（阿里云/腾讯云等）
  2. 添加 CNAME 文件：
    • 在 source/ 目录新建 CNAME 文件（无后缀），内容为：www.yourdomain.com
  3. DNS 解析设置：
    • A 记录 → 指向 GitHub Pages IP（任选其一）：
      1
      2
      3
      4
      185.199.108.153
      185.199.109.153
      185.199.110.153
      185.199.111.153
    • 或 CNAME 记录 → 指向 你的用户名.github.io
  4. GitHub 仓库设置：
    • Settings → Pages → Custom domain 填写域名 → 勾选 ✅ Enforce HTTPS

🛠️ 七、高频问题解决方案

问题 解决方案
部署失败/权限错误 检查 SSH 密钥是否添加；ssh -T git@github.com 测试
页面空白/样式丢失 检查 _config.yml 中 url 是否为部署后地址；清除浏览器缓存
中文路径 404 安装 hexo-abbrlink 插件，配置永久链接
图片不显示 使用相对路径；或设置 _config.yml 中 post_asset_folder: true
部署后内容未更新 hexo clean 清除缓存后重新部署
GitHub Pages 未生效 检查仓库 Settings → Pages → Branch 是否为 main/gh-pages

🔒 八、维护与进阶建议

  • 备份源码：将整个 my-blog 目录（含 source/, themes/, _config.yml）存至私有仓库或网盘
  • 自动化部署：配置 GitHub Actions 实现 push 后自动构建（适合高级用户）
  • 增强功能：
    • 评论系统：Valine / Waline / Gitalk
    • 统计：Google Analytics / 不蒜子
    • SEO：sitemap + robots.txt
  • 更新组件：
    1
    2
    npm update hexo-cli -g      # 更新 Hexo
    cd themes/butterfly && git pull  # 更新主题

💡 最后提醒

  1. 不要删除 .deploy_git 目录（部署缓存，但无需备份）
  2. 所有修改均在本地完成，部署仅推送生成的静态文件
  3. 遇到问题优先查阅：

✨ 恭喜！你的专属技术博客已上线！坚持写作，让知识流动起来～
如有细节疑问，欢迎提供具体报错信息进一步分析！