自定义扩展指南

概述

Hexo 支持通过多种方式自定义博客的外观和功能，无需修改主题源码。

自定义 CSS

文件位置

1
source/css/custom.css

配置注入

在 _config.butterfly.yml 中配置：

1
2
3
inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">

常用自定义样式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/* 自定义主题色 */
:root {
  --primary-color: #49B1F5;
  --link-color: #99a9bf;
}

/* 文章内容样式 */
.post-content {
  line-height: 1.8;
}

/* 代码块样式 */
code {
  font-family: 'Fira Code', monospace;
}

/* 图片圆角 */
.post-content img {
  border-radius: 8px;
}

/* 隐藏元素 */
.hide-on-mobile {
  display: block;
}

@media (max-width: 768px) {
  .hide-on-mobile {
    display: none;
  }
}

Butterfly 主题变量覆盖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* source/css/custom.css */

/* 覆盖主题变量 */
:root {
  --primary-color: #49B1F5;
  --font-size: 16px;
  --content-width: 800px;
}

/* 暗黑模式变量 */
[data-theme="dark"] {
  --primary-color: #7ec8e3;
  --background-color: #1d1e20;
}

自定义 JavaScript

文件位置

1
source/js/custom.js

配置注入

1
2
3
inject:
  bottom:
    - <script src="/js/custom.js"></script>

常用自定义脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 控制台输出
console.log('Welcome to My Blog!');

// 图片点击放大
document.querySelectorAll('.post-content img').forEach(img => {
  img.addEventListener('click', function() {
    window.open(this.src);
  });
});

// 阅读进度条
window.addEventListener('scroll', function() {
  const scrolled = window.scrollY;
  const total = document.documentElement.scrollHeight - window.innerHeight;
  const percent = (scrolled / total) * 100;
  document.querySelector('.reading-progress')?.style.setProperty('width', percent + '%');
});

自定义页面

创建新页面

1
hexo new page "页面名称"

生成目录：source/页面名称/index.md

页面模板

编辑 source/页面名称/index.md：

1
2
3
4
5
---
title: 页面标题
date: 2026-06-19
type: "页面类型"
---

常见页面类型

友情链接页

1
2
3
4
5
---
title: 友情链接
date: 2026-06-19
type: "links"
---

项目展示页

1
2
3
4
5
---
title: 我的项目
date: 2026-06-19
type: "projects"
---

相册页

1
2
3
4
5
---
title: 我的相册
date: 2026-06-19
type: "gallery"
---

静态资源管理

目录结构

1
2
3
4
5
6
7
8
9
10
11
source/
├── img/           # 图片资源
│   ├── favicon.png
│   ├── my-avatar.png
│   ├── bg.jpg
│   └── posts/     # 文章图片
├── css/           # 样式文件
│   └── custom.css
├── js/            # 脚本文件
│   └── custom.js
└── fonts/         # 字体文件

图片管理最佳实践

  1. 命名规范

    1
    2
    my-avatar.png ✓
    My Avatar.png ✗

  2. 目录组织

    1
    2
    3
    4
    5
    6
    7
    8
    9
    source/img/
    ├── favicon.png      # 网站图标
    ├── my-avatar.png    # 头像
    ├── bg.jpg           # 背景图
    └── posts/           # 文章图片
        ├── 2026-06-01/
        │   └── image1.png
        └── 2026-06-02/
            └── image2.png

  3. 图片优化

    • 使用 WebP 格式
    • 压缩图片大小（推荐 TinyPNG）
    • 指定宽高避免布局偏移

资源文件夹

启用后可以为每篇文章创建独立的资源文件夹：

1
2
# _config.yml
post_asset_folder: true

使用方式：

1
![图片](my-post/image.png)

模板覆盖

覆盖主题模板

在 themes/butterfly/layout/ 目录下创建同名文件即可覆盖：

1
2
3
4
5
6
7
themes/butterfly/layout/
├── layout.puggy       # 主布局
├── index.pug          # 首页
├── post.pug           # 文章页
├── page.pug           # 页面
├── archive.pug        # 归档
└── tag.pug            # 标签

创建自定义布局

1
2
3
4
5
6
7
8
// themes/butterfly/layout/page.pug
extend layout

block content
  #page
    h1= page.title
    .post-content
      != page.content

国际化 (i18n)

多语言支持

修改 _config.yml：

1
2
3
language: zh-CN    # 中文
# language: en     # 英文
# language: ja     # 日文

自定义翻译文件

1
themes/butterfly/languages/zh-CN.yml

添加自定义翻译：

1
2
3
4
5
6
7
# themes/butterfly/languages/zh-CN.yml
menu:
  Home: 首页
  Archives: 归档
  Tags: 标签
  Categories: 分类
  About: 关于

CDN 配置

主题 CDN

1
2
3
4
5
# _config.butterfly.yml
CDN:
  internal_provider: local    # 主题资源本地化
  third_party_provider: jsdelivr  # 第三方库使用 CDN
  version: true

自定义 CDN

1
2
CDN:
  custom_format: https://cdn.staticfile.org/${cdnjs_name}/${version}/${min_cdnjs_file}

部署优化

缓存策略

1
2
3
4
5
# Nginx 配置
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

Gzip 压缩

1
2
3
4
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css application/json application/javascript text/xml;

调试技巧

本地调试

1
2
3
4
5
6
7
8
9
10
11
# 清除缓存
hexo clean

# 重新构建
hexo generate

# 启动服务器（调试模式）
hexo server --debug

# 监听文件变化
hexo server --watch

查看生成的 HTML

构建后查看 public/ 目录中的文件

浏览器开发者工具

  • F12 打开开发者工具
  • 查看 Console 错误
  • 检查 Network 资源加载
  • 使用 Elements 面板调试样式

常见自定义需求

修改网站图标

1
2
# _config.butterfly.yml
favicon: /img/favicon.png

修改头像

1
2
3
avatar:
  img: /img/my-avatar.png
  effect: false

修改背景图

1
background: /img/boat.jpg

修改首页副标题

1
2
3
4
5
subtitle:
  enable: true
  effect: true
  sub:
    - "我的博客副标题"

修改页脚信息

1
2
3
4
5
6
footer:
  owner:
    enable: true
    since: 2026
  custom_text: |
    <a href="https://beian.miit.gov.cn/" target="_blank">ICP备案号</a>

下一步