记录我自己用 Hexo + GitHub Pages 搭建博客的全过程，希望也能帮助到你

目录

0. 前言：为什么选择 Hexo + GitHub Pages

这是我第一次完整地“把代码放到网上”。以前总觉得“写博客”要先学会前端、后端、运维……直到真正动手才发现：只要敢敲第一行命令，你就已经赢了一半。整个过程我踩了 7 个坑，也收获了 4 个“哇塞”瞬间。下面把最顺、最快、最稳的路线一次性写给你。

1. 准备工作：必备工具和环境

工具 做什么 快速验证
Node.js ≥ 14 跑 Hexo node -v
Git 上传代码 git --version
GitHub 账号 免费托管静态网站 已有就跳过

⚠️ 国内网络：第一次访问 GitHub 慢，可临时用 Watt Toolkit 加速。

2. 安装 Hexo：简单快捷

1
2
npm install -g hexo-cli     # 全局安装脚手架
hexo -v                     # 看到版本号即成功

3. 初始化博客：快速搭建框架

1
2
3
mkdir my-blog && cd my-blog   # 建个文件夹，名字随意
hexo init                     # 把框架拉下来
npm install                   # 装依赖

目录结构瞬间出现：

1
2
3
4
my-blog
├── _config.yml   # 站点配置
├── source/_posts # 文章放这里
└── themes        # 主题目录

4. 本地测试：查看默认主题

1
hexo server  # 或 hexo s

浏览器打开 http://localhost:4000 —— 默认主题已经能看了！
这一刻的“哇塞”瞬间 #1 ✅

5. 部署到 GitHub Pages：详细步骤

5.1 新建仓库

  • 登录 GitHub → New Repository
  • 仓库名必须是 你的用户名.github.io
  • 选 Public → Create

5.2 一键部署插件

1
npm install hexo-deployer-git --save

5.3 改一行配置

打开 my-blog/_config.yml，拉到最底，改成：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main

⚠️ 冒号后必须有空格，缩进用 2 空格，不要 Tab！

5.4 生成 + 上传

1
2
hexo clean   # 清缓存
hexo g -d    # 生成并部署

首次推送会弹出 GitHub 登录，按提示授权即可。
几分钟后访问 https://你的用户名.github.io ——“哇塞”瞬间 #2 ✅

6. 绑定自定义域名：提升博客专业度

  1. 阿里云/腾讯云买域名（首年 6～10 元）。
  2. GitHub 仓库 → Settings → Pages → Custom domain 填 yourdomain.com → Save。
  3. 域名 DNS 添加两条记录：
记录类型 主机记录 值
A @ 185.199.108.153
A @ 185.199.109.153
A @ 185.199.110.153
A @ 185.199.111.153

生效 5 min～2 h，期间你可以先去写第一篇文章。

7. 撰写第一篇文章：快速发布

1
hexo new post "Hello-我的第一篇博客"

文件自动生成在 source/_posts/Hello-我的第一篇博客.md。
用 Typora / VS Code 打开，顶部 YAML 示例：

1
2
3
title: Hello-我的第一篇博客
date: 2024-08-04 11:11:11
tags: [Hexo, 折腾]

写完保存，再次：

1
hexo g -d

文章秒上线 ——“哇塞”瞬间 #3 ✅

8. 主题选择与美化：提升博客颜值

推荐两个零配置就能好看的主题：

主题 一句话理由 安装
AnZhiYu 国产、文档全中文 git clone https://github.com/anzhiyu-c/hexo-theme-anzhiyu.git themes/anzhiyu
Butterfly 功能最全 git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

改 _config.yml：

1
theme: anzhiyu   # 或 butterfly

再 hexo g -d，网站立刻换装 ——“哇塞”瞬间 #4 ✅

9. 常见问题：避免踩坑指南

  1. 仓库名写错 → 必须是 用户名.github.io。
  2. SSH 没配好 → 用 HTTPS 地址也能推送。
  3. _config.yml 缩进 → 用空格，别用 Tab。
  4. deploy 后域名被重置 → 在 source/ 目录新建 CNAME 文件，内容写自己的域名。
  5. 国内 push 失败 → 多试几次，或开 Watt Toolkit。
  6. 主题更新冲突 → 先备份 _config.theme.yml。

10. 进阶功能：评论区、统计和图床

  • 评论区：用 Giscus（基于 GitHub Discussions，免费）。
  • 访问统计：用 Umami 或 百度统计。
  • 图床：用 GitHub 仓库 + jsDelivr CDN（教程一搜一大把）。

11. 写在最后

4 天前我觉得“这玩意儿好难”；
4 天后我把链接发给了最好的朋友。
原来 “发布”不是终点，而是下一段故事的开始。
希望 4 天后的你，也能把这篇文章转给下一个需要的人。

Happy Hexo！