Hexo：Node.js 静态博客生成器安装与部署指南

Hexo 是一个快速、简单、强大的博客框架，由 Node.js 驱动。它能在几秒内生成静态站点，支持 GitHub Flavored Markdown 和大部分 Octopress 插件，一条命令即可部署到 GitHub Pages、Heroku 等平台，拥有数百个主题与插件。

一、项目官方信息

核心特性：极速生成、支持 GFM 与 Octopress 插件、一键部署到 GitHub Pages 等、强大的 API 可无限扩展、数百主题与插件。

二、官方图片

Hexo 官方 Logo：

三、环境要求

• Node.js（建议 16+，安装见 https://nodejs.org ）。
• npm 或 yarn 包管理器。
• Git（用于部署到 GitHub Pages）。
• 无数据库依赖，生成的是纯静态文件。

四、完整部署步骤

1. 安装 hexo-cli

npm install hexo-cli -g

macOS/Linux 也可使用 Homebrew：

brew install hexo

2. 初始化博客

hexo init blog
cd blog

这会在当前目录新建 blog 文件夹并拉取默认骨架。

3. 安装依赖并启动本地服务

npm install
hexo server

浏览器访问 http://localhost:4000 即可预览默认主题。

4. 写文章

hexo new "Hello Hexo"

在 source/_posts/ 下会生成对应的 Markdown 文件，用编辑器写正文。

5. 生成静态文件

hexo generate

生成结果输出到 public/ 目录，可直接部署到任意静态托管。

6. 部署到 GitHub Pages

安装部署插件：

npm install hexo-deployer-git --save

在站点配置 _config.yml 中配置部署：

deploy:
  type: git
  repo: https://github.com/<用户名>/<用户名>.github.io.git
  branch: main

一键部署：

hexo clean
hexo generate
hexo deploy

稍等片刻即可在 https://<用户名>.github.io 访问。

五、使用方法

常用命令

hexo new "post"      # 新建文章
hexo server          # 本地预览（带实时刷新）
hexo generate        # 生成静态文件
hexo deploy          # 部署
hexo clean           # 清理缓存与生成文件

主题

Hexo 提供数百个主题，见官方主题列表 https://hexo.io/themes/ 。安装主题一般是把主题仓库 clone 到 themes/ 目录，然后在 _config.yml 把 theme 字段改为主题名。

插件

插件列表见 https://hexo.io/plugins/ ，涵盖 SEO、 RSS、图片、评论、搜索等，通过 npm 安装后在配置中启用。

目录结构

.
├── _config.yml        # 站点配置
├── package.json       # 依赖
├── scaffolds/         # 文章模板
├── source/            # 源文件（_posts 为文章）
└── themes/            # 主题

六、常见问题 FAQ

1. hexo 命令找不到？ 全局安装的 npm bin 目录未加入 PATH。确认 npm install -g hexo-cli 成功，或用 npx hexo 替代。

2. 改了主题/配置本地不生效？ 执行 hexo clean 再 hexo server，清理缓存后重启预览。

3. 部署到 GitHub Pages 提示认证失败？ repo 地址建议用 HTTPS + 已配置凭据，或改用 SSH 地址；仓库需是 <用户名>.github.io 或在 Settings 里指定分支。

4. 生成很慢？ 文章很多时生成耗时会增加；可配合 hexo generate --concurrency 或精简主题/插件。

5. 如何自定义站点标题、描述？ 编辑根目录 _config.yml 中的 title、description、url 等字段。

6. 主题安装后不显示？ 确认 themes/ 下目录名与 _config.yml 里 theme: 配置完全一致，并执行 hexo clean 后重新生成。

七、跳转链接

• GitHub 仓库：https://github.com/hexojs/hexo
• 官方网站：https://hexo.io
• 文档：https://hexo.io/docs/
• 主题列表：https://hexo.io/themes/
• 插件列表：https://hexo.io/plugins/