在实际运营独立博客时,我们经常需要在侧边栏挂载赞助商广告、联盟推广代码或通知公告。许多博主误以为调整广告位置必须修改主题源码,这不仅操作繁琐,还会导致后续主题升级时配置丢失。

如果主题不需要更新,完全可以修改源码(如果你有修改源码方法的情况下使用),但是这个只有在需要大幅度定制调整的情况下才建议这样折腾。

接下来将指导你如何完全不修改任何源码,仅通过配置文件的调整,就能在侧边栏的任意位置(例如作者卡片与最新文章之间)精准添加多个自定义广告板块,并彻底掌握其排序逻辑与落地执行方法。

适用场景与核心原理

适用场景
适用于使用 Hexo 搭建并采用 Butterfly 主题的博客系统。无论你想添加单张图片广告、JS 脚本代码(如 Google AdSense)还是纯文本公告,该方法均适用。

核心原理
Butterfly 主题内置了 widget(自定义小部件)功能。通过配置 source/_data/widget.yml 文件,系统会自动将这些内容渲染为标准的卡片样式,并允许通过 order 数值控制其与主题自带卡片(如分类、标签、最新文章)的相对排列顺序。

落地执行步骤

第一步 准备并创建配置文件

在你的 Hexo 博客根目录下,进入 source 文件夹。检查是否存在 _data 文件夹。
如果没有,请手动新建一个名为 _data 的文件夹。进入该文件夹,新建一个文件并命名为 widget.yml(注意必须是 yml 后缀)。

第二步 编写多广告板块配置

打开 widget.yml 文件,你可以通过 top(非粘性区域,所有页面显示)或 bottom(非粘性区域,文章页不显示)来定义广告位置。建议使用 top。

以下是添加多个广告的参考配置格式:

1
2
3
4
5
6
7
8
9
10
top:
- name: 广告位一
icon: fas fa-ad
order: 2
html: '<div style="text-align:center;"><a href="你的跳转链接" target="_blank"><img src="你的图片地址" style="width:100%; border-radius:8px;"></a></div>'

- name: 广告位二
icon: fas fa-bullhorn
order: 3
html: '<div style="text-align:center;"><a href="你的跳转链接" target="_blank"><img src="你的图片地址" style="width:100%; border-radius:8px;"></a></div>'

参数解析

  • name:侧边栏卡片的标题文字。
  • icon:标题旁边的 Font Awesome 图标类名。
  • order:排序权重。数字越小越靠前,这是决定广告出现位置的关键。
  • html:广告的具体代码。支持直接写入 HTML 标签、图片代码或 JS 脚本。

第三步 调整精准排序位置

根据实际业务场景,如果你想将广告放在“作者卡片”与“最新文章”之间,需要了解主题的渲染逻辑:

  1. 主题的“作者卡片”属于固定区域,不参与数值排序。
  2. “最新文章”等其他组件参与排序。
  3. 你只需在 _config.butterfly.yml 中确保最新的文章卡片有默认排序值,然后在 widget.yml 中设置一个小于该值的 order 数字(如 2 或 3),广告就会自动插在固定卡片之后、最新文章之前。

第四步 本地预览与部署

保存所有配置文件后,在终端执行以下命令进行本地预览:

1
hexo clean && hexo g && hexo s

在浏览器中访问 http://localhost:4000,检查侧边栏广告位置是否正确。确认无误后执行 hexo d 部署到线上环境。

最终效果与排错指引

最终效果
完成配置后,无需修改任何 Pug 模板文件或核心源码,你的侧边栏就会按 order 顺序渲染出带有统一卡片样式的自定义广告。即使未来升级 Butterfly 主题版本,该广告配置依然有效。

常见问题排查

  1. 图片显示破损:请检查 html 字段中的图片地址。建议使用完整的网络 URL(如 https:// 开头)或存放在本地 source/images 下的绝对路径。
  2. 广告位置不符合预期:微调 widget.yml 中的 order 数字。与其他组件的排序值进行对比,数值越小位置越靠上。
  3. 代码被拦截:如果使用的是 JavaScript 广告脚本,请检查浏览器是否安装了 AdBlock 等拦截插件,或者尝试在无痕模式下测试。

更新:2026年11月17日,基于版本一基础上,大家可以进一步扩展使用,跟着节奏一步一步操作。

在博客侧边栏添加合作伙伴时候,比如太阳能电池,往往需要展示多张图片。传统的静态图片或生硬淡入淡出的切换方式不仅视觉效果不佳,还容易让访客流失。本操作手册将从实际业务场景出发,手把手指导你如何通过配置文件,在 Butterfly 主题侧边栏中实现多广告位独立、横向平滑过渡且带交互圆点的高质量广告轮播。

方案核心原则为关注点分离:数据配置在 widget.yml,样式在 custom.css,交互逻辑在 custom.js。全程无需修改任何主题源码,保障后续主题版本的平滑升级。

准备工作与文件创建

为了方便管理,请确保你的博客根目录下存在以下三个文件(若不存在请手动创建):

  1. 数据配置:source/_data/widget.yml
  2. 自定义样式:source/css/custom.css
  3. 自定义脚本:source/js/custom.js

随后,打开博客根目录的 _config.butterfly.yml,找到 inject 配置项,确保已正确引入你的 CSS 和 JS 文件:

1
2
3
4
5
inject:
head:
- <link rel="stylesheet" href="/css/custom.css">
bottom:
- <script src="/js/custom.js"></script>
编写自定义样式文件 custom.css

在 custom.css 中写入以下代码。我们利用 Flexbox 排版和 CSS3 的 transform 属性,配合贝塞尔曲线缓动,实现柔和滑动效果:

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
.custom-ad-carousel {
position: relative;
width: 100%;
overflow: hidden;
border-radius: 8px;
background-color: #f0f0f0;
}
.ad-track {
display: flex;
width: 100%;
transition: transform 0.8s cubic-bezier(0.25, 0.46, 0.45, 0.94);
will-change: transform;
}
.ad-track a {
flex-shrink: 0;
width: 100%;
display: block;
}

.ad-track img {
width: 100%;
height: auto;
display: block;
object-fit: cover;
}
.ad-dots {
position: absolute;
bottom: 12px;
width: 100%;
text-align: center;
z-index: 10;
}
.ad-dot {
display: inline-block;
width: 8px;
height: 8px;
margin: 0 5px;
background-color: rgba(255, 255, 255, 0.4);
border-radius: 50%;
cursor: pointer;
transition: background-color 0.3s, transform 0.3s;
box-shadow: 0 1px 3px rgba(0,0,0,0.2);
}
.ad-dot.active {
background-color: #fff;
transform: scale(1.3);
}
编写交互逻辑文件 custom.js

在 custom.js 中写入以下代码。该脚本会自动遍历页面中所有带 .custom-ad-carousel 的容器,为每一个广告位独立生成图片轨道和交互圆点,且互不冲突:

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
(function () {
function initAdCarousels() {
var carousels = document.querySelectorAll('.custom-ad-carousel');
if (!carousels.length) return;

carousels.forEach(function(container) {
var track = container.querySelector('.ad-track');
var dataList = container.querySelectorAll('.ad-data li');
var dotsContainer = container.querySelector('.ad-dots');

if (!track || !dataList.length) return;

var intervalTime = parseInt(container.getAttribute('data-interval')) || 3000;
var ads = Array.from(dataList).map(function(li) {
return {
img: li.getAttribute('data-img'),
link: li.getAttribute('data-link')
};
});

var currentIndex = 0;
var timer = null;
var isAnimating = false;

// 初始化 DOM:生成滑动结构
track.innerHTML = '';
ads.forEach(function(ad, index) {
// 构建 a 标签包裹 img
var a = document.createElement('a');
a.href = ad.link;
a.target = '_blank';
var img = document.createElement('img');
img.src = ad.img;
img.alt = '广告';
a.appendChild(img);
track.appendChild(a);

// 生成圆点
if (dotsContainer) {
var dot = document.createElement('span');
dot.className = 'ad-dot' + (index === 0 ? ' active' : '');
dot.addEventListener('click', function() {
if (isAnimating || currentIndex === index) return;
currentIndex = index;
slideTo(currentIndex);
resetTimer();
});
dotsContainer.appendChild(dot);
}
});

var dots = container.querySelectorAll('.ad-dot');

// 核心滑动逻辑
function slideTo(index) {
isAnimating = true;
// 向左平移,每次移动 100% 的宽度
track.style.transform = 'translateX(-' + (index * 100) + '%)';

// 更新圆点状态
dots.forEach(function(dot, idx) {
dot.classList.toggle('active', idx === index);
});

// 等待 CSS 过渡动画完成(0.6s),解锁动画状态
setTimeout(function() {
isAnimating = false;
}, 600);
}

// 自动轮播
function startTimer() {
timer = setInterval(function() {
if (isAnimating) return;
currentIndex = (currentIndex + 1) % ads.length;
slideTo(currentIndex);
}, intervalTime);
}

function resetTimer() {
clearInterval(timer);
startTimer();
}

// 启动
startTimer();

// 鼠标悬停时暂停
container.addEventListener('mouseenter', function() { clearInterval(timer); });
container.addEventListener('mouseleave', startTimer);
});
}

document.addEventListener('DOMContentLoaded', initAdCarousels);
document.addEventListener('pjax:complete', initAdCarousels);
})();
配置数据源 widget.yml

在 widget.yml 中配置广告数据。为了让方案高度复用,我们通过 data-interval 属性控制每个广告位的播放速度,并通过隐藏的 ul 列表传递数据。

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
top:
# 广告位一,播放间隔 3 秒
- name: 咖啡
icon: fas fa-images
order: 1
html: |
<div class="custom-ad-carousel" data-interval="3000">
<div class="ad-track"></div>
<ul class="ad-data" style="display:none;">
<li data-img="https://placehold.co/600x300/3498db/ffffff?text=AD+1" data-link="https://www.example.com/1"></li>
<li data-img="https://placehold.co/600x300/e74c3c/ffffff?text=AD+2" data-link="https://www.example.com/2"></li>
<li data-img="https://placehold.co/600x300/2ecc71/ffffff?text=AD+3" data-link="https://www.example.com/3"></li>
</ul>
<div class="ad-dots"></div>
</div>

# 广告位二,播放间隔 5 秒,与上面完全独立
- name: 赞助商推荐
icon: fas fa-handshake
order: 2
html: |
<div class="custom-ad-carousel" data-interval="5000">
<div class="ad-track"></div>
<ul class="ad-data" style="display:none;">
<li data-img="https://placehold.co/600x200/f39c12/ffffff?text=Sponsor+A" data-link="https://www.example.com/a"></li>
<li data-img="https://placehold.co/600x200/9b59b6/ffffff?text=Sponsor+B" data-link="https://www.example.com/b"></li>
</ul>
<div class="ad-dots"></div>
</div>
最终效果与业务场景对照

配置保存后,运行 hexo clean && hexo g && hexo s 预览。你将获得以下体验效果:

  1. 平滑横向切换:图片不再生硬地原地闪现,而是像丝带一样平滑左滑,完美呈现 cubic-bezier 带来的加减速质感。
  2. 多广告互不干扰:你可以在侧边栏排布多个轮播组件。每一个组件都拥有自己的时间节奏和图片集合,不会引发定时器错乱。
  3. 直观的交互反馈:底部圆点随图片滑动实时高亮。访客点击任意圆点,轮播会立刻响应并重置计时器。当鼠标悬停在图片上时,轮播自动暂停方便阅读,移开后恢复运转。
  4. 免维护兼容:所有数据都在 widget.yml 中,修改图片或链接无需触碰代码。完全适配 Pjax 无刷新加载机制,页面来回切换也不会导致内存泄漏或功能失效。