想拥有一个真正属于自己的博客，通常有两种路线：使用现成平台，或者自己搭建。前者开箱即用，后者则能让域名、内容、样式和数据都掌握在自己手里。

这套教程会使用 Hexo + Solitude 完成一个现代化中文博客：Hexo 负责把 Markdown 文章生成静态网页，Solitude 负责站点的视觉与交互体验。

本篇先完成 Hexo 的安装与使用。读完后，你会得到一个可以写文章、本地预览并生成静态文件的基础博客。主题美化会放在下篇。

先理解 Hexo 的工作方式

Hexo 是一个基于 Node.js 的静态博客框架。它的工作流程可以概括成：

1
2
3
4
5
6
7
Markdown 文章 + 站点配置 + 主题
                ↓
              Hexo
                ↓
        public/ 静态网站文件
                ↓
   GitHub Pages / Vercel / 服务器

你平时维护的是 Markdown、配置和图片，Hexo 负责把它们转换成 HTML、CSS、JavaScript 等浏览器可以直接访问的文件。

这种方式有几个优点：

  • 写作内容以 Markdown 文件保存，容易迁移和备份
  • 生成结果是静态文件，访问速度快，部署选择多
  • 不需要为博客单独维护数据库
  • 主题、插件和自动化工作流都可以自由配置

需要明确的是，Hexo 本身主要负责内容生成。网站最终长什么样，取决于主题；评论、搜索与访问统计等能力，也通常由主题或插件提供。

一、准备运行环境

当前版本要求

截至 2026 年 7 月，Hexo 8 要求 Node.js 20.19.0 或更高版本。建议直接使用当前的 Node.js LTS，不要再参考旧教程安装 Node.js 12、14 或 16。

开始前需要准备：

  • Node.js 与 npm
  • Git
  • 一个代码编辑器，例如 VS Code
  • 可选的 GitHub 账号和个人域名

安装完成后，在终端检查版本：

1
2
3
node --version
npm --version
git --version

如果 node --version 低于 v20.19.0，先升级 Node.js，再安装 Hexo。

推荐使用版本管理工具

macOS 与 Linux 用户可以使用 nvm、fnm 或 nvs 管理 Node.js。这样既方便切换版本，也能减少全局安装 npm 包时遇到的权限问题。

Windows 用户可以使用官方安装包或 nvm-windows。安装时确认 Node.js 已加入 PATH，重新打开终端后再检查版本。

二、安装 Hexo CLI

使用 npm 全局安装 Hexo 命令行工具：

1
npm install -g hexo-cli

安装完成后检查：

1
hexo version

如果不想全局安装，也可以在项目中安装 Hexo，然后通过 npx hexo 执行命令：

1
2
npm install hexo
npx hexo version

对于第一次搭建博客的人，全局安装 hexo-cli 会更直观；真正的 Hexo 核心依赖仍会保存在每个博客项目自己的 package.json 中。

三、创建第一个 Hexo 站点

选择一个保存项目的目录，然后执行：

1
2
3
hexo init my-blog
cd my-blog
npm install

my-blog 是文件夹名称，可以替换成你自己的项目名。

当前 Hexo 在初始化时通常会自动调用可用的包管理器安装依赖，但进入站点后再执行一次 npm install，可以确保依赖完整。以后从 Git 克隆博客源码，也需要先安装依赖。

现在启动本地服务器：

1
hexo server

浏览器打开：http://localhost:4000/

如果看到 Hexo 默认首页，基础站点就已经运行成功。终端会持续监听文件变化，停止服务时按 Ctrl + C。

端口被占用时，可以换一个端口：

1
hexo server -p 5000

四、认识 Hexo 的目录结构

初始化后的关键目录大致如下：

1
2
3
4
5
6
7
8
my-blog/
├── _config.yml
├── package.json
├── scaffolds/
├── source/
│   ├── _drafts/
│   └── _posts/
└── themes/

_config.yml

Hexo 的站点配置文件，负责标题、作者、语言、网址、永久链接、主题和部署等全局设置。

它和下篇会用到的 _config.solitude.yml 不是同一个文件：前者配置 Hexo 站点，后者配置 Solitude 主题。

package.json

记录 Hexo、主题、插件和 npm 脚本。迁移博客源码时，应提交 package.json 与锁文件，不要提交 node_modules。

scaffolds/

文章、页面和草稿的模板。每次执行 hexo new 时，Hexo 会根据这里的模板创建文件。

source/

博客的内容源目录。正式文章位于 source/_posts，草稿位于 source/_drafts；自定义页面、图片和其他需要复制到网站的文件也通常放在这里。

themes/

传统安装方式下用于保存主题源码。如果通过 npm 安装主题，主题代码会位于 node_modules，配置文件则保存在站点根目录。

public/ 与 db.json

这两个文件会在生成或预览过程中出现。public 是最终静态网站，db.json 是 Hexo 缓存。它们都不是内容源，不要直接编辑。

执行下面的命令会删除它们：

1
hexo clean

五、完成基础站点配置

打开根目录的 _config.yml，先修改最重要的字段：

1
2
3
4
5
6
7
8
9
10
11
title: 我的个人博客
subtitle: 记录学习、作品与生活
description: 一个使用 Hexo 搭建的个人博客
keywords: 个人博客, Hexo, 技术分享
author: Your Name
language: zh-CN
timezone: Asia/Shanghai

url: https://example.com
root: /
permalink: :year/:month/:day/:title/

几个容易忽略的细节：

  • url 要写完整协议，例如 https://example.com
  • 如果博客部署在 https://example.com/blog/，应设置 url: https://example.com/blog 与 root: /blog/
  • YAML 只能使用空格缩进，不要使用 Tab
  • 冒号后需要留一个空格
  • 包含冒号等特殊字符的字符串最好加引号

修改配置后，重启本地服务器，让配置完整生效。

六、创建第一篇文章

在站点根目录执行：

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

Hexo 会在 source/_posts 中创建 Markdown 文件。文件开头的 Front Matter 用于保存文章元数据：

1
2
3
4
5
6
7
8
9
10
---
title: 我的第一篇文章
date: 2026-07-29 16:00:00
categories:
  - 技术
tags:
  - Hexo
  - 博客
description: 记录我的 Hexo 博客搭建过程。
---

分隔线下方就是正文：

1
2
3
4
5
这是我的第一篇 Hexo 博客文章。

## 为什么开始写博客？

我希望把学习过程整理成可以长期检索的内容。

保存文件后，运行中的 hexo server 通常会自动更新页面。

分类和标签有什么区别？

  • 分类可以表达层级，例如“技术 → 前端”
  • 标签彼此平级，例如“Hexo”“Node.js”“静态博客”

一篇文章通常使用一个清晰分类，再添加少量真正有检索价值的标签。标签过多会让归档页面变得杂乱。

七、使用草稿与独立页面

创建草稿

1
hexo new draft "尚未完成的文章"

草稿保存在 source/_drafts，默认不会出现在正式构建中。需要预览草稿时运行：

1
hexo server --draft

写完后发布为正式文章：

1
hexo publish post "尚未完成的文章"

创建关于页面

1
hexo new page "about"

页面会创建在 source/about/index.md。它不会自动出现在导航栏里，安装主题后还需要把 /about/ 加入主题菜单配置。

八、管理文章图片

图片有两种常见管理方式。

全局图片目录

把图片放到 source/images：

1
source/images/avatar.png

文章中使用：

1
![头像](/images/avatar.png)

这种方式简单，适合头像、Logo 和多篇文章共用的图片。

每篇文章独立资源目录

在 _config.yml 中启用：

1
2
3
4
5
post_asset_folder: true

marked:
  prependRoot: true
  postAsset: true

之后执行 hexo new post，Hexo 会同时创建同名资源文件夹。也可以使用 Hexo 标签引用图片：

1
{% asset_img example.jpg 图片说明 %}

选择一种稳定方式长期使用即可。不要把本地绝对路径写进文章，否则换电脑或上线后图片会失效。

九、生成静态网站

本地预览确认无误后，执行：

1
hexo generate

也可以使用缩写：

1
hexo g

生成结果会进入 public。如果想验证最终静态文件，而不是开发模式，可以运行：

1
2
hexo generate
hexo server --static

当页面没有更新、缓存状态异常或更换主题后出现旧文件时，再清理并重建：

1
2
hexo clean
hexo generate

不需要每次写文章都执行 hexo clean。频繁清理只会让下一次构建更慢。

十、把博客部署到线上

Hexo 生成的是静态网站，因此可以部署到 GitHub Pages、Cloudflare Pages、Vercel、Netlify 或自己的服务器。

推荐：使用平台的持续部署

当前 GitHub Pages 官方教程使用 GitHub Actions：源码推送后，由工作流安装依赖、运行 Hexo 构建，再把 public 发布到 Pages。

这种方式的优点是源码与生成结果分离，换电脑后仍能自动构建。使用 GitHub Pages 时，在仓库的 Settings → Pages 中选择 GitHub Actions 作为发布来源。

详细流程可以直接参考 Hexo 官方 GitHub Pages 文档。

另一种方式：hexo-deployer-git

先安装部署插件：

1
npm install hexo-deployer-git --save

在 _config.yml 中配置：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/your-name/your-site.git
  branch: gh-pages

然后执行：

1
2
3
hexo clean
hexo generate
hexo deploy

也可以合并为：

1
hexo generate --deploy

不要把访问令牌、服务器密码等凭据明文写进 _config.yml。优先使用 SSH 密钥、平台 Secrets 或环境变量。

自定义域名使用的 CNAME 文件应放在 source/CNAME，这样每次生成时都会自动复制到 public。

十一、日常写作流程

站点建立后，日常操作可以固定为：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. 创建文章
hexo new post "文章标题"

# 2. 本地预览
hexo server

# 3. 生成静态文件
hexo generate

# 4. 提交源码或执行部署
git add .
git commit -m "新增文章"
git push

建议把以下内容提交到 Git：

  • _config.yml
  • package.json 与锁文件
  • source/
  • 自己维护的主题配置和自定义样式

通常不提交：

  • node_modules/
  • public/，持续部署场景下尤其如此
  • db.json
  • 含密钥的本地环境文件

十二、常见问题

hexo 命令不存在

重新打开终端并检查 npm 全局命令目录是否在 PATH。也可以在项目里使用 npx hexo。

安装时出现 EACCES

不要直接用 sudo npm install -g 作为长期解决方案。推荐通过 nvm、fnm 等工具安装 Node.js，让全局 npm 包位于用户目录。

启动时报 EADDRINUSE

默认的 4000 端口已被其他程序占用，换端口即可：

1
hexo server -p 5000

修改后页面仍是旧内容

先确认文件已保存，再重启开发服务器。仍然异常时执行：

1
2
3
hexo clean
hexo generate
hexo server

YAML 配置报错

重点检查缩进、冒号后的空格和字符串引号。YAML 对格式非常敏感，复制配置时不要混入 Tab。

正文中的模板定界符被解析

双花括号或“花括号 + 百分号”组合会触发 Hexo 使用的 Nunjucks 模板语法。可使用 raw 标签包裹相关内容，或按官方文档配置 disableNunjucks。

下一步：安装 Solitude

到这里，我们已经完成了博客的内容系统：可以创建文章、管理草稿、预览页面、生成静态文件并部署上线。

下一篇会把默认主题替换为 Solitude，并完成站点信息、导航栏、首页、侧边栏、搜索、评论与常用页面配置：

如何用 Hexo 和 Solitude 为自己搭建博客（下）：Solitude 主题的安装与配置

参考资料