在实际运营独立博客时,我们经常需要在侧边栏挂载赞助商广告、联盟推广代码或通知公告。许多博主误以为调整广告位置必须修改主题源码,这不仅操作繁琐,还会导致后续主题升级时配置丢失。
如果主题不需要更新,完全可以修改源码(如果你有修改源码方法的情况下使用),但是这个只有在需要大幅度定制调整的情况下才建议这样折腾。
接下来将指导你如何完全不修改任何源码 ,仅通过配置文件的调整,就能在侧边栏的任意位置(例如作者卡片与最新文章之间)精准添加多个自定义广告板块,并彻底掌握其排序逻辑与落地执行方法。
适用场景与核心原理 适用场景 适用于使用 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 脚本。
第三步 调整精准排序位置 根据实际业务场景,如果你想将广告放在“作者卡片”与“最新文章”之间,需要了解主题的渲染逻辑:
主题的“作者卡片”属于固定区域,不参与数值排序。
“最新文章”等其他组件参与排序。
你只需在 _config.butterfly.yml 中确保最新的文章卡片有默认排序值,然后在 widget.yml 中设置一个小于该值的 order 数字(如 2 或 3),广告就会自动插在固定卡片之后、最新文章之前。
第四步 本地预览与部署 保存所有配置文件后,在终端执行以下命令进行本地预览:
1 hexo clean && hexo g && hexo s
在浏览器中访问 http://localhost:4000,检查侧边栏广告位置是否正确。确认无误后执行 hexo d 部署到线上环境。
最终效果与排错指引 最终效果 完成配置后,无需修改任何 Pug 模板文件或核心源码,你的侧边栏就会按 order 顺序渲染出带有统一卡片样式的自定义广告。即使未来升级 Butterfly 主题版本,该广告配置依然有效。
常见问题排查
图片显示破损 :请检查 html 字段中的图片地址。建议使用完整的网络 URL(如 https:// 开头)或存放在本地 source/images 下的绝对路径。
广告位置不符合预期 :微调 widget.yml 中的 order 数字。与其他组件的排序值进行对比,数值越小位置越靠上。
代码被拦截 :如果使用的是 JavaScript 广告脚本,请检查浏览器是否安装了 AdBlock 等拦截插件,或者尝试在无痕模式下测试。
更新:2026年11月17日,基于版本一基础上,大家可以进一步扩展使用,跟着节奏一步一步操作。
在博客侧边栏添加合作伙伴时候,比如太阳能电池 ,往往需要展示多张图片。传统的静态图片或生硬淡入淡出的切换方式不仅视觉效果不佳,还容易让访客流失。本操作手册将从实际业务场景出发,手把手指导你如何通过配置文件,在 Butterfly 主题侧边栏中实现多广告位独立、横向平滑过渡且带交互圆点 的高质量广告轮播。
方案核心原则为关注点分离 :数据配置在 widget.yml,样式在 custom.css,交互逻辑在 custom.js。全程无需修改任何主题源码,保障后续主题版本的平滑升级。
准备工作与文件创建 为了方便管理,请确保你的博客根目录下存在以下三个文件(若不存在请手动创建):
数据配置:source/_data/widget.yml
自定义样式:source/css/custom.css
自定义脚本: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 ; track.innerHTML = '' ; ads.forEach (function (ad, index ) { 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 ; track.style .transform = 'translateX(-' + (index * 100 ) + '%)' ; dots.forEach (function (dot, idx ) { dot.classList .toggle ('active' , idx === index); }); 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 中配置广告数据。为了让方案高度复用,我们通过 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: - 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> - 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 预览。你将获得以下体验效果:
平滑横向切换 :图片不再生硬地原地闪现,而是像丝带一样平滑左滑,完美呈现 cubic-bezier 带来的加减速质感。
多广告互不干扰 :你可以在侧边栏排布多个轮播组件。每一个组件都拥有自己的时间节奏和图片集合,不会引发定时器错乱。
直观的交互反馈 :底部圆点随图片滑动实时高亮。访客点击任意圆点,轮播会立刻响应并重置计时器。当鼠标悬停在图片上时,轮播自动暂停方便阅读,移开后恢复运转。
免维护兼容 :所有数据都在 widget.yml 中,修改图片或链接无需触碰代码。完全适配 Pjax 无刷新加载机制,页面来回切换也不会导致内存泄漏或功能失效。