Hexo 博客搭建过程记录

Hexo 是一个基于 Node.js 的静态博客框架，生成速度快、主题丰富、部署灵活。这篇文章记录了我从零搭建 Hexo 博客的完整过程，包括环境配置、主题选择、插件安装、自动化部署以及踩坑记录。

环境准备

安装 Node.js 与 npm

Hexo 依赖 Node.js 运行，推荐使用 LTS 版本：

# 确认版本
node -v    # v18+ 即可
npm -v

如果网络环境受限（如国内），建议配置 npm 镜像源加速：

npm config set registry https://registry.npmmirror.com

安装 Hexo CLI

npm install -g hexo-cli

安装完成后就可以用 hexo 命令初始化博客项目了。

初始化博客

hexo init myblog
cd myblog
npm install

hexo init 会自动生成博客骨架目录：

myblog/
├── _config.yml       # 博客配置文件（核心）
├── package.json
├── scaffolds/        # 模板文件
├── source/           # 源文件（文章、图片等）
│   └── _posts/       # 文章目录
└── themes/           # 主题目录

核心配置 _config.yml

title: 我的博客
subtitle: 记录技术与思考
author: Your Name
language: zh-CN
timezone: Asia/Shanghai

# 域名与 URL
url: https://chinazhouwy.github.io
root: /
permalink: :year/:month/:day/:title/

主题选择：Hacker

在主题选择上，我倾向于简洁风。Hacker 主题颜色鲜明、排版专注，适合技术博客。

安装方式：

git clone https://github.com/iissnan/hexo-theme-hacker themes/hacker

在 _config.yml 中启用：

theme: hacker

主题通常有自己的独立配置文件 themes/hacker/_config.yml，可以定制导航栏、社交链接、评论系统等。

主题定制要点

  • 导航栏：添加"首页"、“归档”、“关于"等页面
  • 社交链接：配置 GitHub、知乎等社交账号的图标链接
  • 评论系统：集成 Gitalk 或 Valine 等无后端评论方案

写文章与本地预览

创建新文章：

hexo new "文章标题"

该命令会在 source/_posts/ 下生成一个 Markdown 文件，文件头包含 Front-matter：

---
title: 文章标题
date: 2025-04-30 09:24:55
tags:
  - Hexo
---

本地预览：

hexo server
# 或指定端口
hexo server -p 4000

浏览器打开 http://localhost:4000 即可查看。

额外插件配置

自动部署插件

Hexo 生成的静态文件需要部署到服务器或 Pages 服务。最方便的方式是使用 hexo-deployer-git 插件，直接推送到 GitHub Pages：

npm install hexo-deployer-git --save

在 _config.yml 中添加：

deploy:
  type: git
  repo: git@github.com:chinazhouwy/chinazhouwy.github.io
  branch: main

部署命令：

hexo clean && hexo generate && hexo deploy
# 简写：hexo clean && hexo g && hexo d
  • hexo clean：清除缓存
  • hexo g：生成静态文件
  • hexo d：部署到远端

自动摘要插件（不推荐，已关闭）

npm install hexo-excerpt --save

这个插件会自动从文章正文截取摘要。但自动截取往往不够准确，不如手动在 Front-matter 中设置 excerpt 字段或使用 `

` 标记来控制摘要内容。

部署方案

GitHub Pages 部署

个人主页仓库必须命名为 <用户名>.github.io，例如 chinazhouwy.github.io。配置好 Deployer 后，一条命令即可完成部署。

自动化流程

可以结合 GitHub Actions 实现 CI/CD：每次推送文章到源码仓库，自动触发构建和部署。或者使用 hexo-deployer-git 配合 hexo d 手动部署，简单直接。

遇到的问题

问题一：博客路径多了一级子目录

部署后发现博客可通过 chinazhouwy.github.io 访问，但写文章时引用的资源路径不正确，导致部分资源 404。

排查后发现是 _config.yml 中的 root 配置问题。GitHub Pages 个人主页必须使用根路径：

root: /

如果使用 root: /blog/，就会导致资源请求路径变成 chinazhouwy.github.io/blog/css/style.css，与实际的部署路径不匹配。

问题二：端口号冲突

hexo server 默认使用 4000 端口，如果该端口被占用（例如其他 Hexo 实例或应用），可以杀掉占用进程或换端口：

# 查看端口占用
lsof -i :4000

# 杀掉占用进程
kill -9 <PID>

# 或直接换端口启动
hexo server -p 4001

问题三：图片资源管理

Hexo 的文章引用图片有两种方式：

  1. 放在 source/images/ 下，使用 ![](/images/example.png) 引用
  2. 使用文章资源文件夹，在 _config.yml 中启用 post_asset_folder: true，hexo new 时会同步创建同名资源目录

推荐方式 1，管理更集中、路径更清晰。

日常写作流程

# 新建文章
hexo new "文章标题"

# 本地预览
hexo server

# 写完后生成并部署
hexo clean && hexo g && hexo d

这套流程基本满足日常写作需求。如果有多人协作或需要更复杂的发布流程，可以引入 CI/CD 或使用 GitHub Actions 自动构建。

总结

Hexo 作为一个静态博客框架，“上手快、定制灵活” 是其最大优势。从安装到部署，核心链路清晰：

  1. Install → 2. Init → 3. Theme → 4. Write → 5. Generate → 6. Deploy

对于个人技术博客来说，Hexo + GitHub Pages 仍然是一个很轻量、可靠的组合。如果后续有更复杂的定制需求（如多语言、多作者、分类聚合等），可以考虑迁移到 Hugo 或自建 CMS。

以上就是 Hexo 搭建的全过程记录。遇到的坑不少，但解决之后对静态博客的整个生命周期有了更清晰的理解。