零基础搭建 Hexo 博客：从本地到 GitHub Pages 全流程指南

Hexo 是一个快速、简洁且高效的博客框架，支持使用 Markdown 来编写文章，并能快速生成静态网页，非常适合想要搭建个人博客的同学。本文将带你从零开始，本地搭建 Hexo 博客，并部署到 GitHub Pages。

1. 安装 Hexo 框架

首先需要安装 Node.js ，确保已经配置好环境变量。
接着打开命令行工具（cmd / PowerShell / Terminal），运行以下命令全局安装 Hexo：

1
2
npm install -g hexo-cli
bash1

安装完成后，你可以通过以下命令验证是否安装成功：

1
2
hexo -v
bash1

如果能看到版本号，就说明安装完成。

2. 初始化博客项目

新建一个文件夹，例如 Hexo-blog ，然后进入该文件夹：

1
2
3
mkdir Hexo-blog
cd Hexo-blog
bash12

接着运行初始化命令：

1
2
hexo init
bash1

这会自动生成 Hexo 的基础目录结构和默认配置。

3. 安装依赖

进入到博客目录后，执行以下命令安装依赖：

1
2
npm install
bash1

至此，博客的主体框架就已经准备好了。

4. 本地启动博客

运行以下命令启动本地服务：

1
2
hexo server
bash1

然后在 浏览器 中访问 http://localhost:4000 ，就可以看到默认生成的 Hexo 博客页面啦！

按下 Ctrl + C 可以停止服务。

5. 创建第一篇文章

接下来，我们来写一篇属于自己的第一篇博客文章。

执行以下命令：

1
2
hexo new "我的第一篇文章"
bash1

这时会在 source/_posts/ 目录下生成一个名为 我的第一篇文章.md 的 Markdown 文件 。

你可以用任意 Markdown 编辑器（如 Typora、VS Code）打开并编辑它，例如：

1
2
3
4
5
6
7
8
9
10
---
title: 我的第一篇文章
date: 2025-09-09 14:00:00
tags: [Hexo, 博客]
---

# Hello Hexo

这是我的第一篇 Hexo 博客文章！
markdown123456789

编辑完成后，保存文件，再次启动本地服务：

1
2
hexo server
bash1

刷新浏览器页面，就能看到你写的第一篇博客文章啦 🎉

6. 常用 Hexo 命令速查

命令 作用
hexo new "标题" 新建一篇文章
hexo server 本地启动博客（默认端口 4000）
hexo generate 或 hexo g 生成静态文件
hexo clean 清理缓存和生成的文件
hexo deploy 或 hexo d 部署到远程（如 GitHub Pages）

到这里，你已经成功在本地搭建并运行了 Hexo 博客，并写好了第一篇 Markdown 文章。
下一步就是把它 部署到 GitHub Pages ，让别人也能访问到。

7. 部署 Hexo 博客到 GitHub Pages

7.1 创建 GitHub 仓库

  1. 打开 GitHub ，登录账号。
  2. 点击右上角 New repository 新建仓库。
  3. 仓库名字必须设置为：
1
2
用户名.github.io
1

例如：如果你的 GitHub 用户名是 hexo-user ，那么仓库名就必须是：

1
2
hexo-user.github.io
1

这是 GitHub Pages 的默认规则。

  1. 选择 Public（公开） ，点击 Create repository 完成创建。

👉 详情可以参考这篇文章： 从零开始搭建你的个人博客：使用 GitHub Pages 免费部署静态网站

7.2 安装部署插件

回到本地博客项目目录，运行以下命令安装 Hexo 部署工具：

1
2
npm install hexo-deployer-git --save
bash1

7.3 配置 _config.yml

打开博客根目录下的 _config.yml 文件，找到 deploy 部分。

修改为：

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

注意：

  • 如果你的 GitHub 默认分支是 main ，这里就写 branch: main 。
  • repo 一定要写成你自己的仓库地址。

7.4 部署博客

先生成静态文件：

1
2
hexo generate
bash1

然后执行部署：

1
2
hexo deploy
bash1

第一次运行时，可能会提示输入 GitHub 的用户名和密码。
如果你开启了双重验证，需要使用 Personal Access Token（个人访问令牌） 代替密码。

7.5 访问你的博客

部署完成后，稍等片刻，打开浏览器访问：

1
2
https://用户名.github.io
1

就能看到你刚刚写的博客啦 🎉

7.6 常见问题

  1. Git 未安装
    如果提示 git: command not found ，说明没有安装 Git，需要先到 Git 官网 下载并安装。
  2. 权限错误
    如果提示 Permission denied ，可能是 SSH/Token 没有配置好。推荐使用 HTTPS 仓库地址，并使用 Token 部署。
  3. 分支不对
    部署后访问不到，检查 _config.yml 里的 branch 是否和 GitHub 仓库的默认分支一致。

总结

到这里，你已经完成了：

  • ✅ 本地搭建 Hexo 博客
  • ✅ 写下第一篇 Markdown 文章
  • ✅ 部署到 GitHub Pages，让全世界都能访问

接下来你可以尝试：

  • 更换 Hexo 主题 ，让博客更漂亮
  • 配置 自定义域名 ，让博客网址更个性化
  • 使用 标签、分类 ，整理文章内容
study
零基础搭建 Hexo 博客：从本地到 GitHub Pages 全流程指南
作者
z2004y
发布于
2025年11月20日
更新于
2025年11月24日
许可协议