本篇面向完全没接触过代码的同学。跟着做完，你会得到一个有独立网址（你的名字.github.io）、能写文章、手机电脑都能看的个人博客。

一、先认识几个概念

别急着动手，花两分钟搞清楚我们在做什么。

名词 是什么 在本教程里干嘛
Hexo 一个博客生成工具 把你写的 Markdown 文章变成网页
Butterfly 一个博客主题（皮肤） 让博客好看
Node.js 运行环境 Hexo 依赖它才能运行
Git 版本控制工具 把博客推送到网上
GitHub 代码托管平台 免费存放你的博客
GitHub Pages GitHub 的建站服务 让别人能通过网址访问你的博客

一句话流程：用 Hexo 在本地写文章 → 用 Git 推到 GitHub → GitHub Pages 自动发布 → 全网可访问。

二、准备工作

1. 注册 GitHub 账号

打开 https://github.com/ 注册账号。用户名要记住，因为你的博客网址会是 用户名.github.io。

2. 安装 Node.js

去 https://nodejs.org/ 下载 LTS（长期支持版），一路下一步安装即可。

安装完打开命令行（Windows 按 Win+R 输入 cmd 回车），输入：

1
2
node -v
npm -v

能看到版本号就说明装好了。

国内用户如果后面安装很慢，可以换淘宝镜像：

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

3. 安装 Git

去 https://git-scm.com/ 下载安装，一路下一步。验证：

1
git --version

三、安装 Hexo

在命令行执行：

1
npm install -g hexo-cli

-g 表示全局安装，装一次到处能用。验证：

1
hexo version

四、初始化博客

先在电脑上新建一个空文件夹放博客（比如 D:\blog），然后命令行进入这个文件夹，执行：

1
2
hexo init
npm install

等一会儿，会生成这些文件：

1
2
3
4
5
6
blog/
├── _config.yml        # 站点配置文件（改站名、作者、部署等）
├── package.json
├── source/            # 文章和资源都放这里
│   └── _posts/        # 文章目录（你写的文章在这）
└── themes/            # 主题目录

五、本地预览

1
hexo server

浏览器打开 http://localhost:4000/ ，看到一个默认博客就成功了。按 Ctrl+C 停止。

六、安装 Butterfly 主题

在博客根目录执行（推荐用 npm 安装，升级方便、不会有嵌套 git 仓库的坑）：

1
npm install hexo-theme-butterfly --save

再装主题需要的两个渲染依赖：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

打开 _config.yml，找到 theme 字段改成：

1
theme: butterfly

接着在博客根目录新建一个文件 _config.butterfly.yml，把 node_modules/hexo-theme-butterfly/_config.yml 里的内容全部复制过去。以后改主题配置就改这个文件，升级主题不会丢配置。本文说的"主题配置"都指它。

再次 hexo server 预览，能看到 Butterfly 的样式就对了。

七、站点基础配置（_config.yml）

打开 _config.yml，改这几项：

1
2
3
4
5
6
7
8
9
title: 我的博客                     # 站点标题
subtitle: ""
description: ""
author: 你的名字                    # 作者名（全站署名读这里）
language: zh-CN
timezone: Asia/Shanghai

url: https://用户名.github.io       # 换成你的 GitHub 用户名
permalink: :year/:month/:day/:title/

permalink 是文章网址格式，上面是默认值。想用更短的固定网址，可参考《文章分类、置顶与短链配置》装 abbrlink 插件。

八、主题配置（_config.butterfly.yml）

这里只列最常用的几项，完整外观配置见《如何配置网站外观与个人信息》。

导航菜单：

1
2
3
4
5
6
menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  关于: /about/ || fas fa-heart

格式是 显示名: 路径 || 图标。图标去 https://fontawesome.com/icons 搜，复制 class 名。

头像：准备一张正方形图片放到 source/img/avatar.png（没有 img 文件夹就新建），然后：

1
2
3
avatar:
  img: /img/avatar.png
  effect: false       # true 会一直转圈，一般关掉

建菜单对应页面：菜单里写了的页面要手动建，否则点进去 404：

1
2
3
4
hexo new page tags
hexo new page categories
hexo new page archives
hexo new page about

然后编辑 source/tags/index.md，开头加上 type: tags；source/categories/index.md 加 type: categories。归档页和关于页不用加。

九、写第一篇文章

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

会在 source/_posts/ 生成 我的第一篇文章.md。用 Typora 或任意编辑器打开，开头是 front-matter（两行 --- 之间的配置）：

1
2
3
4
5
6
7
8
---
title: 我的第一篇文章
date: 2026-08-06 14:30:00
tags:
  - 随笔
categories:
  - 生活
---

下面用 Markdown 写正文，常用语法：

1
2
3
4
5
6
7
8
9
10
11
12
# 大标题
## 二级标题

普通段落直接写。

- 列表项一
- 列表项二

**加粗** *斜体* `行内代码`

[链接文字](https://example.com)
![图片说明](图片名.png)

写完 hexo server 预览效果。

十、部署到 GitHub Pages

最后一步，把博客发布到网上。

1. 新建仓库

在 GitHub 点 New repository，名字必须是 用户名.github.io（用户名换成你的）。选 Public，其他不勾，创建。

2. 配置 SSH（让电脑有权推送到 GitHub）

1
2
3
4
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

ssh-keygen -t ed25519 -C "你的邮箱"

一路回车。然后用记事本打开生成的公钥文件（Windows 路径 C:\Users\你的用户名\.ssh\id_ed25519.pub），复制全部内容。

到 GitHub → 右上角头像 → Settings → SSH and GPG keys → New SSH key，Title 随便填，Key 粘贴刚才复制的内容，保存。

验证：

1
ssh -T git@github.com

第一次问 yes/no 输 yes。看到 Hi 用户名! 就成功了。

3. 安装部署插件

1
npm install hexo-deployer-git --save

4. 配置部署信息

打开 _config.yml，翻到最下面的 deploy，改成：

1
2
3
4
deploy:
  type: git
  repo: git@github.com:用户名/用户名.github.io.git
  branch: main

用户名要换成你自己的。repo 地址也能在 GitHub 仓库页面点 Code → SSH 复制。

5. 一键发布

1
hexo clean && hexo g && hexo d

三个命令的作用：

命令 作用
hexo clean 清理缓存
hexo g 生成静态网页
hexo d 推送到 GitHub

第一次推送可能要确认，输 yes。等 1-2 分钟，访问 https://用户名.github.io/ 就能看到你的博客了。

十一、日常使用

博客搭好后，日常写文章就三步：

1
2
3
hexo new "新文章"                  # 1. 建文章
# （用编辑器写内容）
hexo clean && hexo g && hexo d     # 2. 发布

想先看看效果不发布，用 hexo server 本地预览。

完整的写作发布流程（图片处理、草稿、本地预览细节）见《Hexo 博客发布笔记完整教程》。

十二、进阶推荐

博客跑起来后，可以接着折腾：

  • 《如何配置网站外观与个人信息》：改背景、菜单、社交链接、公告
  • 《文章分类、置顶与短链配置》：文章自动归类、置顶、固定短网址
  • 《如何添加书签》：做个网址收藏页

十三、常见问题

Q：hexo server 打不开 localhost:4000？
看命令行有没有报错。端口可能被占用，换一个：hexo server -p 5000。

Q：部署报错 Permission denied (publickey)？
SSH 没配好。重新按第十步生成 key 并添加到 GitHub，确认 ssh -T git@github.com 能通过。

Q：部署成功了但访问 404？
按顺序检查：仓库名是不是严格的 用户名.github.io；仓库是不是 Public；去仓库 Settings → Pages 看是否已开启。

Q：部署后看到的还是旧内容？
GitHub Pages 有缓存，等 1-2 分钟或 Ctrl+F5 强刷。也可去仓库 Actions 页面看部署状态。

Q：中文文章网址又长又丑？
默认网址带中文和日期。装 hexo-abbrlink 插件可生成固定短链（crc32 十六进制，最多 8 位），详见《文章分类、置顶与短链配置》。

Q：图片显示不出来？
用图床时先确认图片 URL 能直接打开。用本地图片时，在 _config.yml 设置 post_asset_folder: true，图片放文章同名文件夹，用裸文件名引用 ![](图片.png)。详见《Hexo 博客发布笔记完整教程》。

小结

步骤 命令 / 操作
装环境 Node.js + Git
装 Hexo npm install -g hexo-cli
建博客 hexo init
装主题 npm install hexo-theme-butterfly --save + 改 theme: butterfly
改配置 _config.yml + _config.butterfly.yml
写文章 hexo new "标题"
发布 hexo clean && hexo g && hexo d

搭一次，以后写文章只需要后两行。