LiaoZiXiong's Blog

Welcome to Hexo! This is your very first post. Check documentation for more info. If you get any problems when using Hexo, you can find the answer in troubleshooting or you can ask me on GitHub.

Quick Start

Create a new post

1

$ hexo new "My New Post"

More info: Writing

Run server

1

$ hexo server

More info: Server

Generate static files

1

$ hexo generate

More info: Generating

Deploy to remote sites

1

$ hexo deploy

More info: Deployment

前言

很多想写博客的朋友，面对市面上的各种博客平台（CSDN、博客园、知乎、简书等）常常陷入选择困难。这些平台要么广告多、要么定制性差、要么数据不归自己掌控。而自己买服务器搭建博客，费用高、维护麻烦。本篇文章介绍的方案是：GitHub Pages + Hexo + 自定义域名。这套方案只需要 ¥10/年的域名费用，就能拥有一个完全属于自己的静态博客——速度快、无广告、高度可定制，真香！

适用人群：懂一点命令行操作、会用 Markdown 写作、喜欢折腾的同学。

准备工作

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

第一步：安装必要软件

1.1 安装 Node.js（含 npm）

Hexo 基于 Node.js，所以必须先安装 Node.js。

1. 前往 nodejs.org 下载 LTS 版本（长期支持版，更稳定）
2. 运行安装包，一路默认安装即可（Windows 用户建议勾选 “Automatically install the necessary tools”）
3. 安装完成后，打开终端（Windows 用 PowerShell 或 CMD，Mac 用终端），验证安装：

1
2
3
4
5

node -v
# 示例输出：v22.22.2

npm -v
# 示例输出：10.9.7

npm 是 Node.js 的包管理器，安装 Node.js 时会自动附带，无需单独安装。

如果两条命令都能正常显示版本号，说明安装成功。如果提示 command not found（Mac）或 “不是内部命令”（Windows），请重启终端再试，或者检查环境变量是否正确配置。

Node.js 是什么？ 简单理解，Node.js 让 JavaScript 可以在浏览器之外运行（比如在你的电脑上跑一个构建工具）。Hexo 就是用 JavaScript 写的博客框架，所以需要 Node.js 来运行。

npm 是什么？ npm（Node Package Manager）就像一个应用商店，你通过它下载各种 JavaScript 工具和库。比如 npm install -g hexo-cli 就是从 npm 下载 Hexo 命令行工具并全局安装。

1.2 安装 Git 并配置

Git 是版本控制工具，Hexo 需要它来将生成的网页推送到 GitHub。

1. 前往 git-scm.com 下载对应系统的版本
2. 安装时保持默认选项即可（Windows 用户如果遇到选项不确定，一路 Next 就对了）
3. 验证安装：

1
2

git --version
# 示例输出：git version 2.54.0.windows.1

安装完成后，必须配置用户信息，否则后续提交会报错：

1
2

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

这两个信息会记录在每次 Git 提交中，方便追溯是谁提交了什么内容。--global 参数表示全局生效，所有 Git 仓库都会用这个配置。

验证配置是否成功：

1
2

git config user.name
git config user.email

如果你的网络访问 GitHub 不稳定（经常 timeout 或拒绝连接），可以配置代理或者考虑使用国内的 Gitee Pages 作为替代方案。

1.3 安装 Hexo（核心框架）

确保 Node.js 和 npm 已正确安装后，执行以下命令全局安装 Hexo 命令行工具：

1

npm install -g hexo-cli

安装完毕后验证：

1

hexo version

如果显示 hexo-cli: x.x.x 以及 Node.js 版本信息，则安装成功。

小科普：hexo-cli 是 Hexo 的命令行工具，-g 表示全局安装（global），安装后可以在任意目录下使用 hexo 命令。而真正的 Hexo 框架代码，是在每个博客项目里通过 npm install 安装的。

第二步：本地创建博客

2.1 初始化博客项目

选择一个合适的目录（比如你的用户目录或文档目录），依次执行：

1
2
3
4
5
6
7
8

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

# 进入项目目录
cd my-blog

# 安装依赖包
npm install

执行 hexo init 时，Hexo 会从 GitHub 克隆官方起始模板 hexo-starter，自动搭建好项目的目录结构。如果网络连不上 GitHub，Hexo 会改用本地备份来初始化。

npm install 会根据 package.json 中声明的依赖，下载所有必需的 npm 包到 node_modules/ 目录。

项目目录结构说明：

1
2
3
4
5
6
7
8
9

my-blog/
├── _config.yml        # 📌 站点全局配置文件（最重要）
├── package.json       # 项目依赖清单
├── scaffolds/         # 文章模板（创建新文章时的默认内容）
├── source/
│   └── _posts/        # 📌 所有文章存放在这里（Markdown 格式）
├── themes/            # 📌 主题目录
├── public/            # 生成的静态文件（执行 hexo generate 后产生）
└── node_modules/      # npm 依赖包（不用手动管）

2.2 本地预览

1
2

hexo server
# 或简写：hexo s

然后在浏览器打开 http://localhost:4000 就能看到博客的样子了。

热更新：Hexo 的本地服务器支持热更新——你修改文章或配置后，刷新浏览器就能看到变化，不需要重启服务器。按 Ctrl+C 停止服务。

如果端口 4000 被占用，可以指定其他端口：

1

hexo server -p 5000

第三步：写文章

3.1 创建文章

1
2

# 创建一篇新文章
hexo new "文章标题"

执行后，Hexo 会在 source/_posts/ 下生成一个 文章标题.md 文件。文件顶部是 Front-matter（用 --- 包裹的元数据区域）：

1
2
3
4
5

---
title: 文章标题          # 文章标题
date: 2026-06-09 11:13:30  # 创建时间
tags:                   # 标签（可选，用于分类）
---

你也可以指定分类和标签：

1

hexo new "文章标题" --tags "Hexo,博客" --categories "教程"

3.2 使用 Markdown 写作

Hexo 文章使用 Markdown 格式，下面是一些常用的 Markdown 语法：

Markdown 的优势在于：纯文本、易读写、兼容性好，写的时候不用管排版，Hexo 会自动转成漂亮的 HTML。

如果你嫌手动写 Markdown 麻烦，可以搭配 Typora、VS Code、Obsidian 等 Markdown 编辑器来写，所见即所得。

第四步：部署到 GitHub Pages

这是最关键的一步——把本地生成的静态网站部署到 GitHub，让全世界都能访问到。

4.1 创建 GitHub 仓库

1. 登录 github.com
2. 点击右上角 + → New repository
3. 仓库名必须填写为：<你的GitHub用户名>.github.io
   • 例如你的 GitHub 用户名是 lzxlog，就创建 lzxlog.github.io
   • 注意：仓库名必须是公开的（Public），否则 GitHub Pages 功能受限
4. 不要勾选 “Add a README file”（我们要推送自己的内容）
5. 点击 Create repository

为什么仓库名必须是这个格式？ 这是 GitHub Pages 的约定：名为 <用户名>.github.io 的仓库，其内容会自动发布到 https://<用户名>.github.io。这就是你的博客网址（还没绑定自定义域名前）。

4.2 安装部署插件

在你的博客项目目录下：

1

npm install hexo-deployer-git --save

hexo-deployer-git 是 Hexo 的 Git 部署插件，负责把生成的静态文件推送到指定的 Git 仓库。--save 表示将它写入 package.json，方便以后在新的电脑上通过 npm install 一键安装所有依赖。

4.3 修改 _config.yml

打开项目根目录下的 _config.yml，在文件最末尾找到（或添加）deploy 配置块：

1
2
3
4
5
6

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main

配置项说明：

• type: git：使用 Git 方式部署
• repo：你的 GitHub 仓库地址，记得替换成你自己的用户名
• branch: main：推送到 main 分支（GitHub 现在默认分支是 main，不是 master）

注意 YAML 缩进：_config.yml 使用 YAML 格式，缩进必须是空格（不能用 Tab），且层级关系要严格正确。如果格式不对，Hexo 会报错。

4.4 执行部署

1
2

# 一键三连：清理 → 生成 → 部署
hexo clean && hexo generate && hexo deploy

这些命令做了什么？

• hexo clean：清除 public/ 目录和缓存（避免旧文件残留导致问题）
• hexo generate（简写 hexo g）：根据 source/ 下的 Markdown 文章和主题模板，生成纯静态的 HTML/CSS/JS 到 public/ 目录
• hexo deploy（简写 hexo d）：将 public/ 目录的内容推送到 GitHub 仓库

首次部署时，终端可能会弹出一个 GitHub 登录窗口让你授权，输入 GitHub 账号密码或 token 即可。后续部署就不需要重复登录了（Windows 凭据管理器会记住）。

部署完成后，在浏览器访问 https://你的用户名.github.io，等待 1-2 分钟让 GitHub Pages 完成构建，就能看到你的博客了！

报错排查：如果 hexo deploy 报权限错误（403），请检查仓库地址是否正确，或者需要在 GitHub 生成 Personal Access Token 来代替密码进行认证。

第五步：绑定自定义域名

如果你有自己的域名，可以让博客使用自定义域名访问，看上去更专业。

5.1 配置 DNS 解析

登录你购买域名的服务商（阿里云、Cloudflare、Namecheap、腾讯云等），进入 DNS 管理页面（通常叫”DNS 解析”或”域名解析”）。

添加 4 条 A 记录（把根域名 lzxlog.xyz 指向 GitHub Pages 的服务器）：

这 4 个 IP 是 GitHub Pages 的官方 IP 地址，全部添加是为了高可用（一个挂了还能走另一个）。这些 IP 可能会变动，建议以 GitHub 官方文档 为准。

添加 CNAME 记录（让 www.lzxlog.xyz 也能访问，并自动跳转到根域名）：

配置示例（以阿里云为例）：

• 主机记录 @ 表示根域名本身（即 lzxlog.xyz）
• 主机记录 www 表示 www.lzxlog.xyz
• TTL 可以保持默认（通常是 600 秒）

5.2 GitHub 仓库设置自定义域名

1. 打开你的 GitHub 仓库页面（用户名.github.io）
2. 点击 Settings 标签
3. 左侧菜单找到 Pages（在 “Code and automation” 分类下）
4. 在 Custom domain 输入框中填入你的域名（如 lzxlog.xyz），点击 Save
5. GitHub 会自动进行 DNS 验证（检查你是否真的拥有这个域名）。验证通过后，会显示 “Your site is published at…”
6. 勾选 Enforce HTTPS —— 这个非常重要！强制启用 HTTPS，保证访问安全

HTTPS 证书由 GitHub 通过 Let’s Encrypt 自动申请和续期，完全免费且无需人工干预。DNS 验证和证书签发可能需要几分钟到几十分钟不等，耐心等待即可。如果长时间未生效，检查 DNS 记录是否填写正确。

5.3 添加 CNAME 文件（关键步骤）

如果不做这一步，每次执行 hexo deploy 之后，GitHub 仓库 Setting 里设置的 Custom domain 可能会被覆盖（变成空），导致域名失效。

解决方案——在博客项目的 source/ 目录下创建一个名为 CNAME 的文件（没有扩展名）：

1
2
3
4
5

# 在 Windows PowerShell 中：
echo "lzxlog.xyz" > source/CNAME

# 在 Mac / Linux 终端中：
echo "lzxlog.xyz" > source/CNAME

把 lzxlog.xyz 替换成你自己的域名。这个文件会被 Hexo 当作静态资源，每次部署时自动推送到 GitHub 仓库，这样域名配置就永远不会丢失了。

原理：GitHub Pages 会读取仓库根目录下的 CNAME 文件来确定自定义域名。Hexo 的 source/ 目录下的文件在 generate 时会原样复制到 public/ 目录，部署后就在仓库根目录了。

第六步：更换主题

Hexo 默认主题（Landscape）功能比较简单，建议换一个好看的主题。

6.1 热门主题推荐

6.2 安装主题（以 Butterfly 为例）

1
2

# 在博客根目录下，将 Butterfly 主题克隆到 themes 目录
git clone https://github.com/jerryc127/hexo-theme-butterfly themes/butterfly

如果 GitHub 连接不上，可以用 Gitee 镜像或直接下载 ZIP 包解压到 themes/butterfly/。

6.3 启用主题

修改博客根目录下的 _config.yml，找到 theme 字段（约在第 95 行附近）：

1
2
3
4
5

# 原来是：
theme: landscape

# 改为：
theme: butterfly

6.4 安装主题依赖插件

有些主题需要额外的插件才能正常工作。以 Butterfly 为例：

1

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

具体需要哪些插件，请查阅你所使用主题的官方文档。

6.5 应用主题配置

• 每个主题都有独立的配置文件（一般在 themes/<主题名>/_config.yml）
• 建议将主题配置文件复制到博客根目录，命名为 _config.<主题名>.yml，这样更新主题时配置不会丢失。Butterfly 主题支持这种用法。
• 根据主题文档调整配置（头像、社交链接、评论系统、统计等）

配置完成后重新部署：

1

hexo clean && hexo generate && hexo deploy

完整架构流程（一张图看懂）

1
2
3
4
5
6
7
8

你写文章(.md) → hexo generate → 生成纯静态网站(HTML/CSS/JS)
                                       ↓
                                 hexo deploy
                                       ↓
                              推送到 GitHub 仓库
                              (用户名.github.io)
                                       ↓
用户访问 lzxlog.xyz → DNS 解析 → GitHub Pages 服务器 → 返回网页

这套架构的巧妙之处在于：

• 不需要自己买服务器：GitHub Pages 免费提供静态网站托管
• 自动 CDN 加速：GitHub Pages 自带全球 CDN，世界各地访问都快
• 免费 HTTPS：GitHub 自动提供 SSL 证书，保证安全
• 版本管理：你的博客源码天然受 Git 版本控制，永远不怕丢
• 一键部署：写文章 → 一条命令部署，整个过程不到 1 分钟

日常写作工作流

把每日写博客的流程固化为以下步骤，熟练后 30 秒就能完成一篇发布：

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

# 1. 创建新文章
hexo new "文章标题"

# 2. 用 Markdown 编辑器打开 source/_posts/文章标题.md，开始写作
#    推荐编辑器：VS Code、Typora、Obsidian

# 3. 本地预览效果
hexo server
# 浏览器打开 http://localhost:4000，边写边看效果

# 4. 确认无误后，一键部署
hexo clean && hexo generate && hexo deploy

# 5. 等待 1-2 分钟，刷新你的域名即可看到新文章

常见问题与解决

❓ 部署后网站打不开 / 显示 404？

• 检查仓库名是否正确——必须是 <用户名>.github.io，拼写要完全一致（区分大小写）
• 进入仓库 Settings → Pages，确认 Branch 设置为 main 且不为 None
• 刚部署完需要等 1-2 分钟让 GitHub Pages 构建完成，别急
• 检查 _config.yml 中的 deploy.repo 地址是否写对了

❓ 域名访问显示 “无法访问此网站”？

• 检查 DNS 的 A 记录和 CNAME 记录是否正确添加
• DNS 修改后需要时间生效（通常几分钟到几小时，极端情况下最长 48 小时）
• 用 ping 你的域名 测试 DNS 是否已解析到 GitHub 的 IP
• 确认仓库 Settings → Pages → Custom domain 已经保存且验证通过

❓ HTTPS 显示”不安全”或证书错误？

• 确认 Settings → Pages 中勾选了 Enforce HTTPS
• 刚设置完自定义域名，证书申请需要时间（通常 10 分钟到几小时），等一等再试
• 如果超过 24 小时仍未生效，取消 Enforce HTTPS 再重新勾选，触发证书重新申请

❓ hexo deploy 报错 “Permission denied”？

• 如果 GitHub 开启了双因素认证（2FA），用密码推送会失败，需要创建 Personal Access Token
• 在 GitHub → Settings → Developer settings → Personal access tokens → 生成一个新 token（勾选 repo 权限）
• 部署时用 token 代替密码

❓ 想把博客源码也备份起来？

• 博客源码（Hexo 配置文件、Markdown 文章、主题配置等）可以存放在一个私有仓库中
• 生成的静态文件部署在公开的 <用户名>.github.io 仓库中
• 这样源码安全、网站公开，两全其美

❓ 文章中的图片怎么处理？

• 方法一：将图片放在 source/images/ 目录下，文章中引用 ![](/images/xxx.png)
• 方法二：使用图床（如 SM.MS、腾讯云 COS、阿里云 OSS），文章中引用图片链接
• 方法三：使用 GitHub Issues 作为图床

成本总结

不需要买服务器，不需要操心运维、备份、安全补丁。GitHub 帮你搞定一切。

写在最后

搭建博客只是一个开始，更重要的是坚持写下去。技术博客不仅能帮自己梳理知识体系，还能帮助到有相同问题的人。哪怕一开始写得不好也没关系，写着写着就进步了。

祝你的博客越写越好 🚀

参考资料

• Hexo 官方文档
• GitHub Pages 官方文档
• Butterfly 主题文档