这篇文章记录我从零开始,在阿里云轻量服务器上用 Hexo + Butterfly 主题搭建个人博客的完整过程,包括踩过的几个大坑。如果你也想搭一个同款博客,照着做就行。

为什么选 Hexo + Butterfly

  • Hexo:基于 Node.js 的静态博客生成器,生成纯静态页面,速度快、安全(无数据库)、可托管在任何静态服务器。
  • Butterfly:Hexo 最流行的中文博客主题之一,外观现代、功能齐全(分类、标签、搜索、侧边栏、评论、暗黑模式等)。

我参照的博客 linzyblog.netlify.app 就是 Hexo + Butterfly,效果很专业,所以决定照着搭一个。

一、准备:服务器和环境

  • 一台云服务器(我用阿里云轻量应用服务器,系统 Alibaba Cloud Linux 3)
  • 一个域名(已解析到服务器 IP)
  • 服务器上装有 nginx(我用宝塔面板管理)

二、安装 Node.js

Hexo 需要 Node.js。国内服务器直接从官方源下载很慢,用 npmmirror 国内镜像:

1
2
3
4
5
6
cd /usr/local
curl -fSL -o /tmp/node.tar.gz https://cdn.npmmirror.com/binaries/node/v18.20.4/node-v18.20.4-linux-x64.tar.gz
tar xzf /tmp/node.tar.gz -C /usr/local
ln -sfn /usr/local/node-v18.20.4-linux-x64 /usr/local/node
ln -sf /usr/local/node/bin/node /usr/local/bin/node
ln -sf /usr/local/node/bin/npm /usr/local/bin/npm

把 npm 源也换成国内镜像,后面装包快很多:

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

三、安装 Hexo 和 Butterfly

1
2
mkdir -p /www/wwwroot/hexo-blog/source/_posts
cd /www/wwwroot/hexo-blog

写一个 package.json,把 Hexo、Butterfly 主题和必要的渲染器都列上:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "name": "hexo-blog",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "hexo": "^6.3.0",
    "hexo-theme-butterfly": "^5.5.4",
    "hexo-renderer-pug": "^2.0.0",
    "hexo-renderer-stylus": "^3.0.1",
    "hexo-renderer-marked": "^6.3.0",
    "hexo-generator-feed": "^3.0.0",
    "hexo-generator-searchdb": "^1.4.0"
  }
}

然后 npm install。注意 GitHub 在国内访问不通,所以主题和插件都走 npm 镜像,而不是 git clone。

四、配置

_config.yml(Hexo 主配置)关键项:

1
2
3
4
5
6
title: 我的博客
language: zh-CN
timezone: Asia/Shanghai
url: https://你的域名
permalink: posts/:title/
theme: butterfly

_config.butterfly.yml(主题配置)覆盖导航、配色、侧边栏:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder
  关于: /about/ || fas fa-heart

aside:
  enable: true
  position: right
  card_author:
    enable: true
  card_categories:
    enable: true
  card_tags:
    enable: true

search:
  use: local_search

别忘了创建标签页和分类页(否则点进去 403):

1
2
hexo new page tags     # 在 source/tags/index.md 加 type: tags
hexo new page categories

五、一个大坑:hexo generate 不工作

装完直接 hexo generate,结果只打印了一段帮助信息,一个文件都没生成。

排查发现:Hexo 加载配置的源码里有一行

1
if (!ctx.env.init) return;  // env.init 不为 true 就跳过加载配置

这个 env.init 标志正常由 hexo-cli 设置,但全局装的 hexo-cli 没设它,导致 Hexo 根本没读 _config.yml(主题还停留在默认的 landscape,文章识别为 0 篇)。

解决办法:写一个生成脚本 build.sh,用 Node 直接调 Hexo API 并手动设 env.init:

1
2
3
4
5
6
7
8
9
10
11
12
#!/bin/bash
export PATH="/usr/local/node/bin:/usr/local/bin:$PATH"
cd /www/wwwroot/hexo-blog
node -e "
const Hexo = require('hexo');
const h = new Hexo(process.cwd(), {});
h.env.init = true;
h.init().then(() => h.call('clean')).then(() => h.call('generate')).then(() => {
  console.log('build ok');
  return h.exit();
}).catch(e => { console.error(e.message); process.exit(1); });
"

之后再执行 ./build.sh,就能正常生成 30 多个静态文件了。

六、部署:nginx 托管静态文件

Hexo 生成的静态文件在 public/ 目录,让 nginx 直接托管:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
server {
    listen 443 ssl;
    http2 on;
    server_name 你的域名;
    root /www/wwwroot/hexo-blog/public;
    index index.html;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

nginx -s reload 后,域名访问就是博客了。HTTPS 直接复用之前申请的证书。

七、又一个坑:首页白屏(FontAwesome)

上线后发现首页偶尔一片空白。排查发现:Butterfly 默认从 cdn.jsdelivr.net 加载 FontAwesome 图标的 CSS,而 jsdelivr 在国内访问不稳定,这个 CSS 又是渲染阻塞的——加载超时,浏览器就一直白屏。

解决办法:把 FontAwesome 本地化。下载到 source/lib/font-awesome/,然后改主题模板 head.pug:

1
2
- link(rel='stylesheet', href=url_for(theme.asset.fontawesome))
+ link(rel='stylesheet', href=url_for('/lib/font-awesome/css/all.min.css'))

从此不再依赖外部 CDN,白屏问题消失。

八、写文章

文章是 source/_posts/ 下的 Markdown 文件,带 frontmatter:

1
2
3
4
5
6
7
8
9
10
11
---
title: 文章标题
date: 2026-08-09 10:00:00
tags:
  - 标签
categories:
  - 分类
cover: https://图片地址
---

正文内容……

写完执行 ./build.sh 重新生成,刷新博客就能看到新文章。

后台可以接一个 Markdown 编辑器(带实时预览和工具栏):标题/标签/分类用表单填,正文直接写 Markdown 即可。注意别用纯富文本编辑器——它会存成 HTML、破坏 Markdown 格式。

总结

最终效果:一个外观专业、加载飞快、全站 HTTPS 的个人博客。整个过程踩了两个大坑(hexo 的 env.init、jsdelivr 白屏),但都解决了。

如果你也准备搭,记住两点:

  1. 国内服务器:Node/Hexo/主题用 npmmirror 镜像,别依赖 GitHub。
  2. 静态博客的 CDN:图标/字体尽量本地化,别用 jsdelivr 这种国内不稳的 CDN。

祝你也能拥有自己的博客