教程 Hexo教程教程热门精选 Hexo 博客搭建

🌐 Hexo 博客搭建教程

xiaoming2024-03-212026-04-18

📝 前言

如果你想快速拥有一个属于自己的博客，但又不想折腾传统动态网站，那么 Hexo 会是非常适合入门的选择。它是一个轻量、速度快、生态成熟的静态博客框架，配合 GitHub Pages、Vercel 等平台，可以低成本完成发布。

[!TIP]
如果你还想把博客部署到服务器，可以继续阅读站内另一篇教程：/posts/e039465e.html。

🎯 一、这篇教程你将完成什么

学完这篇文章后，你可以完成以下事情：

安装 Hexo 所需环境
初始化一个全新的博客项目
本地预览博客效果
安装并配置主题
部署到 GitHub Pages
可选部署到 Vercel

[!NOTE]
本文更适合第一次接触 Hexo 的新手，尽量按顺序操作，不建议跳步。

🔧 二、环境准备

1. 安装 Node.js

Node.js 是 Hexo 的运行环境，必须先安装。

操作步骤：

打开 Node.js 官网
下载 LTS 稳定版
按默认选项完成安装
打开命令提示符验证版本

node -v

如果能正常输出版本号，就说明安装成功。

为了提升依赖安装速度，建议顺手切换 npm 镜像源：

npm config set registry https://registry.npmmirror.com

2. 安装 Git

Git 用于管理博客源码，也用于后续部署。

操作步骤：

打开 Git 官网下载页
按默认选项完成安装
安装后执行以下命令确认是否正常

git --version

3. 安装 Hexo CLI

环境准备完成后，安装 Hexo 命令行工具：

npm install -g hexo-cli

安装完成后，检查版本：

hexo -v

4. 配置 GitHub 账号信息

如果你打算部署到 GitHub Pages，建议先配置全局 Git 用户信息：

git config --global user.name <你的用户名>
git config --global user.email <你的邮箱>

查看是否配置成功：

git config -l

5. 配置 SSH 连接 GitHub

为了后续推送代码更方便，建议配置 SSH：

ssh-keygen -t rsa -C <你的邮箱>

一路回车后，打开用户目录下的 .ssh 文件夹，复制 id_rsa.pub 内容，添加到 GitHub：

头像 → Settings → SSH and GPG keys → New SSH key

添加完成后测试连接：

ssh -T git@github.com

[!TIP]
首次连接时看到确认提示，输入 yes 即可。

🚀 三、新建 Hexo 项目

环境安装完成后，就可以正式创建博客了。

1. 初始化项目

在你想放置博客的位置打开终端，执行：

hexo init <项目名>
cd <项目名>

例如：

hexo init my-blog
cd my-blog

2. 安装依赖

npm i

安装完成后，一个基础的 Hexo 博客就已经创建好了。

👀 四、本地预览博客

为了先确认博客能正常运行，建议先进行本地预览。

1. 生成静态文件

hexo generate

2. 启动本地服务

hexo server

浏览器打开：

http://localhost:4000/

如果页面能正常打开，就说明博客已经运行成功。

[!NOTE]
常用缩写命令也可以记一下：hexo cl、hexo g、hexo s。

⚙️ 五、了解基础目录结构

新手最容易迷糊的就是项目目录，下面这几个位置最常用：

_config.yml：Hexo 全局配置文件
source/_posts/：文章存放目录
themes/：主题目录
public/：生成后的静态文件目录
scaffolds/：文章模板目录

其中你最常接触的通常是：

写文章：source/_posts/
改站点信息：_config.yml
改主题样式：主题目录

🎨 六、安装与配置主题

默认主题能用，但不够好看。大多数人都会换成更适合博客展示的主题。

1. 选择主题

如果你想快速做出更完整的个人博客，推荐优先看成熟主题文档，例如：

Butterfly 主题

2. 安装主题

不同主题安装方式略有不同，一定要以该主题官方文档为准。

3. 修改主题配置

一般会涉及两个部分：

Hexo 全局配置 _config.yml
主题自己的配置文件

[!WARNING]
主题文档一定要认真看，很多“页面空白”“样式错乱”“文章不显示”问题，往往都是配置漏改导致的。

🌐 七、部署到 GitHub Pages

如果你希望博客免费上线，GitHub Pages 是非常常见的方案。

1. 创建仓库

在 GitHub 创建一个仓库，仓库名格式必须为：

<用户名>.github.io

例如你的用户名是 xiaoming，仓库名就必须叫：

xiaoming.github.io

2. 安装部署插件

npm install hexo-deployer-git --save

3. 修改部署配置

打开根目录下的 _config.yml，添加或修改 deploy：

deploy:
  type: git
  repository: git@github.com:<用户名>/<用户名>.github.io.git
  branch: main

4. 执行部署

hexo clean
hexo generate
hexo deploy

如果终端出现 Deploy done，说明部署成功。

稍等一会儿后，访问：

https://<用户名>.github.io

就可以看到你的博客了。

☁️ 八、可选部署到 Vercel

除了 GitHub Pages，也可以把 Hexo 部署到 Vercel。

适合人群

想要更简单的可视化部署
想绑定自己的域名
想后续继续扩展更多项目

大致流程

登录 Vercel 官网
使用 GitHub 账号授权登录
导入你的 Hexo 仓库
点击部署
在后台绑定域名

[!TIP]
如果你的博客源码已经放在 GitHub，Vercel 的接入通常会非常顺手。

🧩 九、常见问题

1. 运行命令提示找不到 `hexo`

通常是 hexo-cli 没安装成功，重新执行：

npm install -g hexo-cli

2. 本地能看，部署后样式丢失

优先检查：

_config.yml 中的 url
root 配置
主题静态资源路径

3. 推送 GitHub 失败