准备工作

在开始之前，你需要准备好以下三样东西：

• 一台电脑（Windows / macOS / Linux 均可）
• 一个 GitHub 账号（免费注册：github.com）
• 一个文本编辑器（推荐 VS Code，免费好用）

1. 安装 Node.js

Hexo 基于 Node.js 运行，所以第一步是安装 Node.js。

打开浏览器，访问 https://nodejs.org，下载 LTS 版本（长期支持版，更稳定）。下载后双击安装包，一路点击 “Next” 完成安装。

LTS 是什么意思？ Long Term Support，也就是这个版本经过了长期测试，稳定性最好。不要选最新版（Current），可能有不兼容的问题。

安装完成后，验证是否安装成功。打开终端：

• Windows：按 Win + R，输入 cmd，回车
• macOS：按 Cmd + Space，搜索 “终端”，回车

在终端中输入以下命令，如果看到版本号就说明安装成功了：

1
2
3
4
5

node -v
# 应该输出类似 v20.x.x 的版本号

npm -v
# 应该输出类似 10.x.x 的版本号

npm 是什么？ 它是 Node.js 自带的包管理器。你可以把它理解为”应用商店”——通过它安装各种工具和插件，包括 Hexo。

2. 安装 Git

Git 是版本控制工具，Hexo 通过 Git 把博客推送到 GitHub Pages。

访问 https://git-scm.com/downloads，下载对应操作系统的安装包，一路默认安装即可。

验证安装：

1
2

git --version
# 应该输出类似 git version 2.x.x

安装完成后，还需要配置你的用户名和邮箱（替换成你自己的）：

1
2

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

为什么要配置这个？ 每次提交代码时，Git 都会记录是谁提交的，这个用户名和邮箱会显示在你的 GitHub 提交记录中。

3. 注册 GitHub 账号

如果你还没有 GitHub 账号，打开 github.com，点击右上角 “Sign up”，按提示注册。记住你的用户名，后面会用到。

创建博客项目

4. 安装 Hexo 脚手架

在终端中输入以下命令，全局安装 Hexo 命令行工具：

1

npm install -g hexo-cli

这个命令会安装 hexo 命令到你的系统中。-g 表示全局安装，安装一次后可以在任何目录使用。

验证安装：

1
2

hexo version
# 应该输出 hexo-cli 和各项依赖的版本号

5. 初始化博客

选择一个目录来存放你的博客。比如在桌面上创建一个 blog 文件夹：

1
2
3
4
5
6
7
8
9
10
11

# 先切换到桌面
cd Desktop

# 初始化一个名为 blog 的 Hexo 项目
hexo init blog

# 进入项目目录
cd blog

# 安装依赖包
npm install

hexo init blog 做了什么？ 它会自动下载 Hexo 的默认项目模板，包括基本的目录结构、默认主题（landscape）、一篇示例文章以及必要的配置文件。整个过程大约需要 1-2 分钟。

6. 了解目录结构

初始化完成后，你的 blog 文件夹结构如下：

1
2
3
4
5
6
7
8

blog/
├── _config.yml          # 网站配置文件（最重要）
├── package.json         # 项目依赖信息
├── scaffolds/           # 文章模板
├── source/              # 你的文章和页面放这里
│   └── _posts/          # 所有博客文章（Markdown 文件）
├── themes/              # 主题文件夹
└── node_modules/        # 依赖包（不要手动修改）

需要关注的只有两个地方： _config.yml 配置文件，和 source/_posts/ 文章目录。其他目录一般不需要改动。

7. 本地预览

在项目目录下运行：

1

hexo server

或者简写为：

1

hexo s

打开浏览器，访问 http://localhost:4000，你应该能看到一个默认的博客页面。

提示： 按 Ctrl + C 可以停止本地服务器。每次修改配置或文章后，刷新浏览器即可看到变化（不需要重启服务器）。

安装 Fluid 主题

默认主题比较朴素。我们换成 Fluid，这是一款 Material Design 风格的高颜值主题。

8. 安装主题

在博客项目目录下运行：

1

npm install hexo-theme-fluid --save

这个命令会把 Fluid 主题下载到 node_modules/hexo-theme-fluid/ 目录。

9. 启用主题

用编辑器（VS Code）打开项目根目录下的 _config.yml 文件，找到 theme 字段，修改为：

1

theme: fluid

注意： _config.yml 文件中有很多配置项，不要被吓到。现在只需要关心 theme 这一个字段。

10. 创建主题配置文件

Fluid 主题提供了丰富的定制选项。我们需要把主题的默认配置文件复制到博客根目录：

1
2

# 复制主题配置文件到博客根目录
cp node_modules/hexo-theme-fluid/_config.yml _config.fluid.yml

macOS/Linux 用户 用上面的命令。
Windows 用户 如果 cp 命令无效，直接用文件管理器复制文件即可：进入 node_modules/hexo-theme-fluid/ 目录，找到 _config.yml，复制到 blog/ 根目录，重命名为 _config.fluid.yml。

11. 基础主题配置

打开 _config.fluid.yml，修改以下几项基本信息：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 网站标题
navbar:
  blog_title: "你的博客名称"

# 首页大标题
banner:
  title: "你的博客名称"
  subtitle: "一句个性签名"

# 头像
about:
  avatar: /img/avatar.png
  name: "你的名字"
  intro: "你的自我介绍"

配置优先级： _config.fluid.yml 的优先级高于主题自带的 _config.yml，所以你只需要在 _config.fluid.yml 中覆盖你想修改的部分即可。

12. 放入头像

找一张正方形的头像图片，重命名为 avatar.png，放入 source/img/ 目录（如果没有 img 文件夹就新建一个）。

写第一篇文章

13. 创建文章

1

hexo new "我的第一篇文章"

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

命名建议： 文件名尽量用英文，Hexo 会自动处理中文标题。如果文件名是中文，生成的 URL 里会有长长的编码，不好看。

14. 理解 Front Matter

打开刚生成的文章文件，你会看到顶部的 --- 包裹区域：

1
2
3
4
5
6
7
8

---
title: 我的第一篇文章
date: 2026-05-30 12:00:00
tags: []
categories: []
---

这里是文章正文，支持 Markdown 语法。

这个 --- 包裹的区域叫做 Front Matter，用来定义文章的元信息：

tags 和 categories 的区别： 标签更细粒度，一篇文章可以有多个标签；分类更宏观，一篇通常只有一个分类。

15. 写文章

在 --- 下方用 Markdown 语法写正文。如果你还不太熟悉 Markdown，下面是最常用的语法速查：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 一级标题
## 二级标题
### 三级标题

**粗体文字**
*斜体文字*

- 无序列表项 1
- 无序列表项 2

1. 有序列表项 1
2. 有序列表项 2

[链接文字](https://example.com)

![图片描述](图片路径)

> 引用文字

`行内代码`

​```bash
# 代码块
echo "Hello World"
​```

注意： 代码块的三个反引号在实际使用时前面不要有那个零宽空格（​），这里加它是为了避免 Markdown 解析冲突。你直接打三个反引号即可。

写完文章后，运行 hexo s 在本地预览效果。

部署到 GitHub Pages

现在你的博客在本地可以看了，接下来把它发布到互联网上。

16. 创建 GitHub 仓库

GitHub Pages 的仓库名有固定格式：**你的用户名.github.io**

比如你的 GitHub 用户名是 zhangsan，仓库名就是 zhangsan.github.io。

操作步骤：

1. 登录 GitHub
2. 点击右上角 + → New repository
3. Repository name 填写 你的用户名.github.io
4. 选择 Public（公开）
5. 不要勾选 “Add a README file”（重要！）
6. 点击 “Create repository”

为什么仓库名必须这样？ GitHub 规定，只有命名为 用户名.github.io 的仓库才会自动开启 GitHub Pages 功能。其他名字的仓库也可以开 Pages，但 URL 不同。

17. 配置部署信息

打开项目根目录的 _config.yml（注意不是 _config.fluid.yml），找到 deploy 部分，修改为：

1
2
3
4

deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: gh-pages

例如你的 GitHub 用户名是 zhangsan：

1
2
3
4

deploy:
  type: git
  repo: https://github.com/zhangsan/zhangsan.github.io.git
  branch: gh-pages

branch: gh-pages 是什么意思？ 部署的内容会被推送到仓库的 gh-pages 分支，而不是 main 分支。这样可以把源代码和生成的静态文件分开管理。

18. 安装部署插件

1

npm install hexo-deployer-git --save

这个插件让 Hexo 能够自动把生成的静态文件推送到 GitHub。

19. 一键部署

1

hexo clean && hexo deploy

这个命令做了三件事：

1. hexo clean — 清除之前生成的旧文件
2. hexo generate（隐式）— 重新生成静态网站
3. hexo deploy — 推送到 GitHub

首次部署时会弹出 GitHub 登录窗口，授权即可。之后部署不需要重复登录。

部署失败？ 如果遇到 Permission denied 错误，可能是 Git 认证没配置好。可以改用 SSH 方式：在 GitHub 设置中添加 SSH Key，然后把 repo 地址改为 git@github.com:用户名/用户名.github.io.git。

20. 查看你的博客

等待 1-2 分钟，打开浏览器访问 https://你的用户名.github.io，你应该就能看到自己的博客了！

如果看到 404 页面，去 GitHub 仓库的 Settings → Pages，确认 Source 选的是 gh-pages 分支。

绑定自定义域名

使用 用户名.github.io 看起来不够专业。你可以买一个自己的域名，比如 yourname.com。

21. 购买域名

推荐以下域名服务商（支持支付宝/微信支付）：

• NameSilo — 价格实惠，送免费 WHOIS 隐私保护
• 腾讯云 — 国内用户方便
• 阿里云 — 国内用户方便

一般 .com 域名首年约 50-80 元，.top 等域名更便宜，首年只需几块钱。

22. 配置 DNS

在域名服务商的管理后台，添加以下 DNS 记录：

什么是 CNAME？ 它相当于一个别名/转发——告诉浏览器”当你访问 yourname.com 时，实际上是访问 你的用户名.github.io“。从用户的角度完全看不到后面那个地址。

如果你用 Cloudflare 管理 DNS，添加 A 记录指向 GitHub Pages 的 IP 地址也可以：

1
2
3
4

A    @    185.199.108.153
A    @    185.199.109.153
A    @    185.199.110.153
A    @    185.199.111.153

23. 创建 CNAME 文件

在你的博客项目的 source/ 目录下，新建一个名为 CNAME 的文件（没有扩展名）：

1
2

source/
└── CNAME

在文件中写入你的域名（不带 https://，不带路径）：

1

brightnewmoon.top

为什么要 CNAME 文件？ 每次部署时，Hexo 会把这个文件也上传到服务器。GitHub 看到这个文件就知道”这个仓库绑定了这个域名”，从而正确处理访问请求。

24. GitHub 设置

进入你的 GitHub 仓库 → Settings → Pages，在 Custom domain 中填入你的域名，点击 Save。

GitHub 会自动检查 DNS 配置是否正确。如果显示 “DNS check successful”，说明配置成功。

25. 启用 HTTPS

在同一个 Pages 设置页面，勾选 Enforce HTTPS。GitHub 会自动为你申请和续期免费的 Let’s Encrypt SSL 证书。这个功能在 DNS 配置生效后（通常需要几分钟到几小时）才能开启。

进阶美化

以下操作会让你的博客更上一层楼。

26. 开启暗色模式

在 _config.fluid.yml 中：

1
2
3
4

color_scheme:
  enable: true
  # 可选 auto / light / dark
  default: auto

auto 表示跟随用户系统的明暗设置自动切换。

27. 开启文章阅读进度条

1
2
3
4

reading_progress:
  enable: true
  color: "#7c3aed"
  height: 3px

28. 开启代码高亮和复制按钮

1
2
3
4
5
6
7

code:
  copy_btn: true
  language: true

highlight:
  enable: true
  line_number: true

这样代码块右上角会有一个复制按钮，读者可以一键复制代码。

29. 添加友情链接页

1

hexo new page links

编辑 source/links/index.md，添加：

1
2
3
4
5
6
7

---
title: 友情链接
date: 2026-05-30
type: links
---

这里是我的朋友们。

然后在 _config.fluid.yml 中配置友链数据：

1
2
3
4
5
6

links:
  items:
    - title: "小明的主页"
      url: "https://xiaoming.com"
      intro: "一个有趣的博客"
      avatar: "https://xiaoming.com/avatar.png"

30. 添加评论系统（Giscus）

Giscus 是一个基于 GitHub Discussions 的免费评论系统，无广告、不收集隐私。

第一步：安装 Giscus GitHub App

打开 https://github.com/apps/giscus，点击 Install，选择你的博客仓库。

第二步：获取配置参数

打开 https://giscus.app/zh-CN，填写你的仓库名，按提示操作，最后会生成一段配置代码，从中可以提取：

• data-repo
• data-repo-id
• data-category
• data-category-id

第三步：配置到 Fluid

在 _config.fluid.yml 中：

1
2
3
4
5
6
7
8
9
10

comments:
  enable: true
  type: giscus
  giscus:
    repo: "你的用户名/你的用户名.github.io"
    repo_id: "从 giscus.app 获取"
    category: "Announcements"
    category_id: "从 giscus.app 获取"
    lang: "zh-CN"
    mapping: "pathname"

配置完成后重新部署，每篇文章底部就会出现评论区。

31. 自定义 CSS

在 source/css/ 目录下创建 custom.css 文件，然后在 _config.fluid.yml 中引用：

1

custom_css: /css/custom.css

你可以在这个文件中覆盖任何主题样式。比如修改主题色：

1
2
3
4
5
6
7

:root {
  --accent-color: #7c3aed;
}

[data-user-color-scheme='dark'] {
  --accent-color: #a78bfa;
}

32. 添加网站图标

准备一个 SVG 或 PNG 图标，放到 source/img/favicon.svg，然后在 _config.fluid.yml 中：

1

favicon: /img/favicon.svg

日常使用

博客上线后，日常操作就三件事：

写新文章：

1
2
3

hexo new "文章标题"
# 编辑 source/_posts/文章标题.md
hexo s    # 本地预览

部署发布：

1

hexo clean && hexo deploy

备份源代码：
建议把整个博客项目的源代码也推到一个 GitHub 仓库（私人仓库即可），这样换电脑也能继续写博客。

常见问题

Q：部署后页面样式错乱？

A：检查 _config.yml 中的 url 和 root 配置是否正确。如果是 用户名.github.io 仓库，root 应该是 /。

Q：图片不显示？

A：图片放在 source/img/ 目录下，文章中引用时使用 /img/图片名.png（以 / 开头的绝对路径）。

Q：修改配置后没有生效？

A：执行 hexo clean 清除缓存，再重新生成。有些配置修改后本地预览不会马上生效。

Q：中文文件名变成乱码 URL？

A：这是 URL 编码。建议文章文件名用英文，中文标题在 Front Matter 的 title 字段中写。

Q：怎么让百度收录我的博客？

A：GitHub Pages 会屏蔽百度爬虫。可以考虑用国内 CDN 加速，或者使用双线部署（GitHub Pages + Gitee Pages / 云服务器）。

搭建博客只是一个开始，坚持写作才是最重要的。祝你博客之旅愉快！