以下是使用 Hexo 在 GitHub 上搭建个人博客的详细教程,涵盖从环境准备到博客发布的完整流程:
一、环境准备
1. 安装 Node.js
Hexo 基于 Node.js 运行,需先安装:
- 下载地址:Node.js 官网(推荐 LTS 版本,含 npm 包管理器)
- 验证安装:打开终端,输入以下命令,显示版本号即成功
Terminal window node -v # 例如 v18.17.1npm -v # 例如 9.6.7
2. 安装 Git
用于将博客部署到 GitHub,同时管理代码版本:
- 下载地址:Git 官网
- 验证安装:终端输入
git --version
,显示版本号即成功
二、注册 GitHub 并创建仓库
1. 注册 GitHub 账号
- 访问 GitHub 官网,注册账号(已有账号可跳过)。
2. 创建博客仓库
- 点击右上角
+
→New repository
- 仓库名必须为:
用户名.github.io
(例如yourname.github.io
,yourname
是你的 GitHub 用户名,小写) - 描述可选,勾选
Public
,点击Create repository
三、安装 Hexo 并初始化博客
1. 安装 Hexo -cli
终端输入以下命令全局安装 Hexo 命令行工具:
npm install -g hexo-cli
验证安装:hexo -v
显示版本信息即成功。
2. 初始化博客项目
- 选择一个本地文件夹(例如
D:\blog
),终端进入该目录:Terminal window cd D:\blog # Windows 示例,Mac/Linux 用 cd ~/blog - 初始化 Hexo 项目:
Terminal window hexo init myblog # 创建名为 myblog 的文件夹并初始化cd myblog # 进入项目目录 - 安装依赖:
Terminal window npm install
3. 目录结构说明
初始化后生成的核心文件/文件夹:
_config.yml
:博客配置文件(关键)source/
:存放文章(_posts/
子文件夹)、图片等资源themes/
:主题文件夹(默认自带landscape
主题)public/
:生成的静态网页(部署到 GitHub 的内容)
四、本地预览博客
- 生成静态文件:
Terminal window hexo generate # 简写 hexo g - 启动本地服务器:
Terminal window hexo server # 简写 hexo s - 浏览器访问
http://localhost:4000
,即可看到默认博客页面(默认有一篇「Hello World」文章)。
五、配置博客基础信息
编辑 _config.yml
(用 VS Code、Notepad++ 等编辑器打开),修改以下关键配置:
# Site(网站基本信息)title: 你的博客名称 # 例如 "技术笔记"subtitle: 副标题 # 例如 "记录学习之路"description: 博客描述 # 用于 SEOauthor: 你的名字 # 作者名language: zh-CN # 语言(中文)timezone: Asia/Shanghai # 时区
# URL(部署后访问地址)url: https://yourname.github.io # 替换为你的 GitHub Pages 地址root: /permalink: :year/:month/:day/:title/ # 文章链接格式
保存后,重启本地服务器(hexo s
)可看到修改效果。
六、发布第一篇文章
-
终端执行以下命令创建新文章:
Terminal window hexo new "我的第一篇文章" # 简写 hexo n "标题"会在
source/_posts/
目录下生成我的第一篇文章.md
文件。 -
编辑 Markdown 文章:
- 用编辑器打开
我的第一篇文章.md
,顶部是「Front-matter」(文章信息),格式如下:---title: 我的第一篇文章date: 2025-10-07 10:00:00tags: [Hexo, 教程]categories: 技术---这里是文章内容,支持 Markdown 语法。例如:# 一级标题## 二级标题**加粗文本** - 编写完成后保存。
- 用编辑器打开
-
重新生成并预览:
Terminal window hexo g # 生成静态文件hexo s # 启动服务器,访问 localhost:4000 查看新文章
七、更换主题(可选)
Hexo 支持多种主题,以热门的「Next」主题为例:
- 下载主题到
themes/
目录:Terminal window git clone https://github.com/next-theme/hexo-theme-next.git themes/next - 编辑
_config.yml
,修改主题配置:theme: next # 改为下载的主题文件夹名 - 生成并预览:
hexo g && hexo s
,查看主题效果。
八、部署博客到 GitHub
1. 安装部署插件
终端输入以下命令安装 hexo-deployer-git
:
npm install hexo-deployer-git --save
2. 配置部署信息
编辑 _config.yml
,添加以下配置(替换为你的 GitHub 仓库地址):
deploy: type: git repo: https://github.com/yourname/yourname.github.io.git # 仓库 HTTPS 地址 branch: main # 分支(GitHub 新仓库默认分支为 main,旧仓库可能是 master)
- 仓库地址获取:进入你的 GitHub 仓库 → 点击
Code
→ 复制 HTTPS 链接。
3. 部署到 GitHub
终端执行以下命令:
hexo clean # 清理缓存(可选,避免旧文件冲突)hexo g # 生成静态文件hexo d # 部署到 GitHub(简写,完整命令 hexo deploy)
- 首次部署会提示输入 GitHub 账号密码或 Token(推荐用 Token,安全性更高:GitHub 账号 →
Settings
→Developer settings
→Personal access tokens
→ 生成含repo
权限的 Token,部署时输入 Token 作为密码)。
4. 访问博客
部署成功后,等待 1-2 分钟,浏览器访问 https://yourname.github.io
,即可看到你的博客!
九、常用命令总结
命令 | 作用 |
---|---|
hexo new "标题" | 创建新文章 |
hexo g | 生成静态文件 |
hexo s | 启动本地服务器(预览) |
hexo d | 部署到 GitHub |
hexo clean | 清理缓存和生成的文件 |
十、后续操作建议
- 自定义主题:修改
themes/主题名/_config.yml
配置主题细节(如导航栏、侧边栏等)。 - 添加评论功能:多数主题支持集成 Disqus、Valine 等评论系统。
- 绑定域名(可选):购买域名后,在 GitHub 仓库
Settings
→Pages
中配置自定义域名。
按照以上步骤操作,即可快速搭建并运行你的 Hexo 博客!如果遇到问题,可参考 Hexo 官方文档 或 GitHub 相关教程排查。