Hexo 建站教程

以下是一个简明且实用的 Hexo 建站教程，适合初学者，基于最新信息（截至2025年7月）并结合 GitHub Pages 部署，帮助你快速搭建个人博客。

一、前言

Hexo 是一个快速、简洁且高效的静态博客框架，基于 Node.js，支持 Markdown 格式，能快速生成静态网页，适合托管在 GitHub Pages 上。它完全免费、轻量，适合个人博客，且无需复杂服务器维护。

二、准备工作

在安装 Hexo 之前，需要准备以下环境：

1. 安装 Node.js

下载地址：https://nodejs.org/en
建议安装最新 LTS 版本（至少 Node.js 12.0，推荐最新版）。
安装后，检查版本：
node -v
npm -v

2. 安装 Git

下载地址：https://git-scm.com/download

选择适合你操作系统的版本，安装后配置用户信息：

git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"

3. 注册 GitHub 账号

前往 https://github.com 注册并验证邮箱。
创建一个名为 <你的用户名>.github.io 的仓库（例如 username.github.io），用于托管博客。

4. 配置 SSH 密钥

生成 SSH 密钥：
ssh-keygen -t rsa -C "你的GitHub邮箱"
连续回车（无需输入密码），密钥生成后位于
~/.ssh/id_rsa.pub
。
复制 id_rsa.pub 内容，登录 GitHub，进入 Settings > SSH and GPG keys > New SSH key，粘贴并保存。

测试 SSH 连接：

ssh -T git@github.com

出现

Hi username! You've successfully authenticated

表示成功。

三、安装 Hexo

1. 安装 Hexo CLI

全局安装 Hexo：
npm install -g hexo-cli

中国用户可使用 cnpm 加速：

npm install -g cnpm --registry=https://registry.npm.taobao.org
cnpm install -g hexo-cli

2. 初始化 Hexo 项目

创建博客文件夹并初始化：

mkdir Hexo-Blog
cd Hexo-Blog
hexo init
npm install

初始化后目录结构：

.
├── _config.yml         # 站点配置文件
├── package.json        # 依赖信息
├── scaffolds           # 模板文件夹
├── source              # 文章和资源文件夹
│   ├── _drafts         # 草稿文件夹
│   └── _posts          # 文章文件夹
├── themes              # 主题文件夹
└── public             # 生成的静态文件

3. 本地预览

启动本地服务器：
hexo server
访问 http://localhost:4000，查看默认博客页面。
如端口被占用，可更改端口：
hexo server -p 5000

四、配置 Hexo

1. 修改站点配置文件

编辑

Hexo-Blog/_config.yml

：

title: 你的博客标题
subtitle: 你的博客副标题
description: 博客描述（用于SEO，建议包含关键词）
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai
url: https://你的用户名.github.io

注意：冒号后需加空格。

2. 安装部署插件

安装

hexo-deployer-git

：

npm install hexo-deployer-git --save

配置

_config.yml

的部署信息：

deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io.git
  branch: main

3. 更换主题

默认主题为

landscape

，可更换为 Next 等：

git clone https://github.com/theme-next/hexo-theme-next themes/next

修改
_config.yml
：
theme: next
清理并重新生成：
hexo clean
hexo generate

五、撰写和发布文章

1. 创建新文章

创建 Markdown 文章：
hexo new "文章标题"
文章生成在 source/_posts/文章标题.md。

2. 编辑文章

编辑 Markdown 文件，顶部为 Front-matter：

---
title: 文章标题
date: 2025-07-28 21:18:00
categories:
  - 分类1
  - 分类2
tags:
  - 标签1
  - 标签2
---
文章正文（Markdown 格式）

3. 生成和部署

生成静态文件：
hexo generate
部署到 GitHub Pages：
hexo deploy
访问 https://你的用户名.github.io 查看博客。

4. 常用命令

创建页面：hexo new page "页面名称"
清理缓存：hexo clean
生成：hexo g
预览：hexo s
部署：hexo d
组合：hexo d -g

六、绑定个人域名（可选）

1. 购买域名

在阿里云、Namesilo 等购买域名（约几十元/年）。
中国用户需完成域名备案。

2. 配置域名解析

获取 GitHub Pages IP：

ping 你的用户名.github.io

通常为

185.199.108.153

等。

添加 A 记录：
- 类型：A 记录
- 主机记录：@
- 记录值：GitHub Pages IP
添加 CNAME 记录（子域名如 www）：
- 类型：CNAME 记录
- 主机记录：www
- 记录值：你的用户名.github.io

3. 配置 Hexo

在
source
文件夹创建
CNAME
文件（无后缀），内容：
你的域名
例如：
www.yourdomain.com

4. 重新部署

执行 hexo g 和 hexo d，通过域名访问。

七、常见问题及解决

端口被占用
- 更改端口：
  hexo server -p 5000
部署失败
- 确保安装 hexo-deployer-git。
- 检查 SSH 密钥和 _config.yml 中的 repo 和 branch。
EACCES 权限错误
- 参考 npm 官方指南修复权限：https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

国内网络问题

使用 cnpm 加速：

npm install -g cnpm --registry=https://registry.npm.taobao.org

主题配置问题
- 主题的 _config.yml（位于 themes/主题名）需单独配置，参考主题文档。

八、进阶功能

添加插件
- 安装压缩插件：
  npm install hexo-all-minifier --save
- 更多插件：https://hexo.io/plugins/
SEO 优化
- 设置 _config.yml 的 description 和关键词。
- 安装站点地图插件：
  npm install hexo-generator-sitemap --save
评论系统
- 集成 Disqus、Gitalk 等，参考主题文档。
多平台部署
- 可部署到 Gitee、Coding 等以提高国内访问速度。

九、参考资源

官方文档：https://hexo.io/zh-cn/docs/
主题推荐：https://hexo.io/themes/
示例博客：https://juemuren4449.github.io
详细教程：https://zhuanlan.zhihu.com/p/145304245
腾讯云教程：https://cloud.tencent.com/developer/article/1691742

十、总结

通过以上步骤，你可在30分钟内完成 Hexo 博客搭建并部署到 GitHub Pages。Hexo 免费、轻量、易于定制，适合喜欢 Markdown 的用户。如需更详细指导或有其他问题，请随时提问！