从零创建一个 Hexo 博客

你将完成什么#

创建一个能在本地预览的 Hexo 博客，发布第一篇文章，并理解源文件、主题和生成目录之间的关系。

前置条件#

安装当前受支持的 Node.js LTS 和 Git，并验证：

node --version
npm --version
git --version

本文只完成本地站点。发布到 GitHub Pages 请继续阅读关联文章。

初始化项目#

使用 npx 可以避免依赖全局 Hexo CLI：

mkdir my-blog
cd my-blog
npx hexo-cli init .
npm install

主要目录如下：

my-blog/
├── _config.yml
├── package.json
├── scaffolds/
├── source/
│   └── _posts/
└── themes/

• source/ 保存文章和页面源文件。
• themes/ 保存主题实现。
• public/ 是生成结果，可以重新构建，不应作为唯一内容来源。

创建第一篇文章#

npx hexo new post "hello-hexo"

编辑 source/_posts/hello-hexo.md，确保 frontmatter 使用合法 YAML：

---
title: Hello Hexo
date: 2026-08-05 10:00:00
tags:
  - Hexo
---

YAML 使用空格缩进，键名后的冒号必须跟空格。

本地预览#

npx hexo clean
npx hexo generate
npx hexo server

打开终端提示的本地地址，检查首页、文章页、代码块和静态图片。修改内容后通常会自动刷新；配置或主题变化异常时重新执行 clean 和 generate。

选择主题#

从 Hexo Themes 选择仍在维护、文档清晰且支持当前 Hexo 版本的主题。按主题自己的安装文档操作，不要复制不同版本的配置片段混用。

安装前记录当前 Git 状态：

git init
git add .
git commit -m "Initialize Hexo blog"

这样主题配置出现问题时，可以查看具体差异并恢复。

验证结果#

npx hexo generate
test -f public/index.html

同时确认浏览器控制台没有资源 404，文章日期和永久链接符合预期。提交 source/、配置和依赖锁文件，不提交 node_modules/。

下一步#

• Hexo documentation
• 将 Hexo 站点发布到 GitHub Pages