Hexo博客搭建与多机同步

本文于 2026 年 5 月全面更新，基于 Hexo 7.x + Butterfly 5.x 主题重写，替换了过时的工具版本和配置方式。

一、博客架构原理

核心流程：本地 *.md → Hexo 渲染为静态 HTML → Git 推送到服务器裸库 → git-hooks 自动同步到网站根目录。

本地编辑 (source/_posts/*.md)
    ↓ hexo generate
静态文件 (public/)
    ↓ git push
服务器裸库 (blog.git)
    ↓ post-receive hook
网站根目录 (/var/www/html/blog/)
    ↓ Nginx
用户访问 (https://your-domain)

也可部署到 GitHub Pages / Vercel / Netlify 等平台，无需自建服务器。

二、本地环境安装

2.1 安装 Git

平台	方式
Windows	下载 Git for Windows 安装
macOS	`brew install git`
Ubuntu/Debian	`sudo apt install git -y`
CentOS/RHEL	`sudo yum install git -y`

安装后配置：

git config --global user.name "YourName"
git config --global user.email "you@example.com"
ssh-keygen -t ed25519 -C "you@example.com"

建议使用 ed25519 算法生成密钥，比 rsa 更安全更短。

2.2 安装 Node.js

Hexo 7.x 要求 Node.js >= 18.0.0。推荐使用 nvm 管理版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 安装并使用 LTS 版本
nvm install --lts
nvm use --lts
# 验证
node -v   # >= 18.x
npm -v

Windows 推荐使用 fnm 或直接从 Node.js 官网下载 LTS 安装包。

三、Hexo 初始化与配置

3.1 安装 Hexo CLI 并初始化

npm install -g hexo-cli
hexo init blog
cd blog
npm install

3.2 核心 `_config.yml` 配置

# Site
title: 你的博客标题
subtitle: '副标题'
description: '博客描述'
keywords: '关键词1,关键词2'
author: YourName
language: zh-CN
timezone: 'Asia/Shanghai'

# URL
url: https://your-domain.com
permalink: article/:abbrlink.html

abbrlink:
  alg: crc32
  rep: hex

# Writing
post_asset_folder: true

# Extensions
theme: butterfly

# Deployment
deploy:
  type: git
  repo: git@your-server:/home/git/blog.git
  branch: master

3.3 常用命令

命令	说明
`hexo new "文章标题"`	新建文章
`hexo server`	本地预览 (http://localhost:4000)
`hexo generate`	生成静态文件
`hexo deploy`	部署
`hexo clean`	清除缓存和静态文件

简写：hexo s、hexo g、hexo d、hexo cl。常用组合：hexo cl && hexo g -d。

四、Butterfly 主题配置

4.1 安装

Hexo 5.0+ 推荐通过 npm 安装主题：

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

在 _config.yml 中设置 theme: butterfly。

4.2 主题配置文件

在博客根目录创建 _config.butterfly.yml，Hexo 会自动合并主题默认配置。常用配置：

# 导航菜单
menu:
  首页: / || fas fa-home
  分类: /categories/ || fas fa-folder-open
  标签: /tags/ || fas fa-tags
  归档: /archives/ || fas fa-archive
  关于: /about/ || fas fa-heart

# 本地搜索
search:
  use: local
  placeholder: 搜索文章...

# 侧边栏
aside:
  enable: true
  position: right
  display:
    archive: true
    category: true
    tag: true

# 暗黑模式
darkmode:
  enable: true
  button: true
  auto_change_mode: 1

# 代码高亮主题
highlight_theme: mac

# 文章版权声明
post_copyright:
  enable: true
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

# 字数统计与阅读时长
wordcount:
  enable: true
  post_wordcount: true
  post_min2read: true

# Pjax 加速页面切换
pjax:
  enable: true

# 图片懒加载
lazyload:
  enable: true
  field: post

# 阅读模式
readmode:
  enable: true

4.3 创建必要页面

hexo new page categories
hexo new page tags
hexo new page about

分别编辑 source/categories/index.md、source/tags/index.md，添加 type: categories 和 type: tags。

4.4 本地搜索

安装搜索插件：

npm install hexo-generator-search --save

在 _config.yml 中添加：

search:
  path: search.xml
  field: post
  content: true

五、服务器端搭建（Nginx + Git Hooks）

5.1 安装 Git 和 Node.js

# CentOS/RHEL
sudo yum install git -y
# 安装 nvm + Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

5.2 创建 git 用户并配置免密登录

adduser git
passwd git

将 git 用户加入 sudo 组（编辑 /etc/sudoers 添加 git ALL=(ALL) ALL）。

配置 SSH 免密登录：

su - git
mkdir ~/.ssh && chmod 700 ~/.ssh
vim ~/.ssh/authorized_keys  # 粘贴本地公钥
chmod 600 ~/.ssh/authorized_keys

本地测试：ssh git@your-server

5.3 Nginx 配置

sudo yum install nginx -y

HTTP 配置 /etc/nginx/conf.d/blog.conf：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    ssl_certificate     /etc/nginx/cert/fullchain.pem;
    ssl_certificate_key /etc/nginx/cert/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;

    root /var/www/html/blog;
    index index.html;

    location ~* \.(ico|gif|jpg|jpeg|png|bmp|swf|svg|woff|woff2|ttf|eot)$ {
        access_log off;
        expires 30d;
    }
    location ~* \.(js|css)$ {
        access_log off;
        expires 7d;
    }

    access_log /var/log/nginx/blog.access.log;
}

使用 certbot 自动获取 Let’s Encrypt 免费 SSL 证书：sudo certbot --nginx -d your-domain.com

授权目录：sudo chown -R git:git /var/www/html/blog

六、Git 自动化部署

6.1 服务器端创建裸库

su - git
cd ~
git init --bare blog.git

6.2 配置 post-receive 钩子

创建 ~/blog.git/hooks/post-receive：

#!/bin/sh
GIT_REPO=/home/git/blog.git
TMP_GIT_CLONE=/tmp/blog
PUBLIC_WWW=/var/www/html/blog

git clone $GIT_REPO $TMP_GIT_CLONE
rm -rf $PUBLIC_WWW/*
cp -rf $TMP_GIT_CLONE/* $PUBLIC_WWW
rm -rf $TMP_GIT_CLONE

chmod +x ~/blog.git/hooks/post-receive

也可用更简单的方式：git --work-tree=/var/www/html/blog --git-dir=/home/git/blog.git checkout -f

6.3 部署

hexo clean && hexo generate --deploy

七、多台电脑同步编辑

利用 Git 分支：hexo 分支保存源文件，master 分支用于发布静态内容。

7.1 `.gitignore` 配置

node_modules/
public/
.deploy_git/
.idea/
.arts/
.codeartsdoer/
*.log

7.2 首次配置

cd blog
git init
git checkout -b hexo
git remote add origin git@your-server:/home/git/blog.git
git add .
git commit -m "init blog source"
git push -u origin hexo

7.3 其它电脑拉取

git clone -b hexo git@your-server:/home/git/blog.git blog
cd blog
npm install
hexo server  # 验证

7.4 日常更新流程

git pull origin hexo           # 先拉取最新
# ... 编辑文章 ...
hexo cl && hexo g -d           # 生成并部署
git add .
git commit -m "update: 文章描述"
git push origin hexo           # 推送源文件

八、常用插件与优化

8.1 推荐插件

插件	用途	安装
hexo-abbrlink	生成永久短链接	`npm i hexo-abbrlink --save`
hexo-generator-search	本地搜索	`npm i hexo-generator-search --save`
hexo-wordcount	字数统计与阅读时长	`npm i hexo-wordcount --save`
hexo-renderer-pug	Butterfly 依赖	`npm i hexo-renderer-pug --save`
hexo-renderer-stylus	Butterfly 依赖	`npm i hexo-renderer-stylus --save`

8.2 性能优化

hexo-neat（HTML/CSS/JS 压缩）：

npm install hexo-neat --save