使用hexo在github搭建博客详细教程 • 枫铃 BLOG

以下是使用 Hexo 在 GitHub 上搭建个人博客的详细教程，涵盖从环境准备到博客发布的完整流程：

一、环境准备

1. 安装 Node.js

Hexo 基于 Node.js 运行，需先安装：

下载地址：Node.js 官网（推荐 LTS 版本，含 npm 包管理器）
验证安装：打开终端，输入以下命令，显示版本号即成功
Terminal window
```
node -v   # 例如 v18.17.1
npm -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 项目：

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: 博客描述    # 用于 SEO
author: 你的名字         # 作者名
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:00
tags: [Hexo, 教程]
categories: 技术
---
这里是文章内容，支持 Markdown 语法。
例如：
# 一级标题
## 二级标题
**加粗文本**

编写完成后保存。

重新生成并预览：

hexo g  # 生成静态文件
hexo s  # 启动服务器，访问 localhost:4000 查看新文章

七、更换主题（可选）

Hexo 支持多种主题，以热门的「Next」主题为例：

下载主题到 themes/ 目录：

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 相关教程排查。