版本：1.4.0 | 日期：2026-06-02
概述
为 Lumin 博客主题实现了完整的广告管理功能，前后台全栈打通，支持 Google AdSense、百度联盟、必应广告及自定义代码，共 9 个广告位覆盖全站关键位置。
架构设计
1数据层 API 层 渲染层
2─────── ──────── ───────
3data/ads.toml ←→ Go Handler ←→ Hugo Partial
4 ↕ GET/PUT /api/ads 9 个位置模板
5Vue 管理页 render-ad.html
6(border-card Tab) (核心渲染引擎)
9 个广告位
| 优先级 | ID | 名称 | 页面范围 | 特色 |
|---|---|---|---|---|
| 🥇 P0 | home_banner_below | 首页 Banner 下方 | 仅首页 | 居中横幅，≤60px |
| 🥇 P0 | sidebar_widget | 侧边栏 Widget | 全站有侧栏 | 融入 widget 风格 |
| 🥇 P0 | header_below | Header 下方横幅 | 全站 | 窄幅 + ✕ 关闭按钮 |
| 🥈 P1 | content_before | 文章内容前 | 文章页 | ≥400 字阈值 |
| 🥈 P1 | content_after | 文章内容后 | 文章页 | ≥400 字阈值 |
| 🥈 P1 | post_bottom | 文章底部 | 文章页 | 文章 footer 之后 |
| 🥈 P1 | list_between | 列表文章间 | 列表页 | 每 N 篇插入 |
| 🥈 P1 | toc_sidebar | TOC 侧边栏 | 文章页(有目录) | TOC 卡片下方 |
| 🥉 P2 | footer_above | 页脚上方 | 全站 | 窄幅横幅兜底 |
三级开关控制
- 全局开关 — 关闭后全站不显示任何广告
- 广告位开关 — 单独控制某个位置是否启用
- 单条广告开关 — 每条广告代码可独立启停
三种展示模式
- fixed：固定显示（仅显示第一条启用的广告）
- random：随机显示（每次刷新随机选一条）
- rotate：轮播展示（自动切换，可设间隔和最大条数）
支持的广告提供商
- Google AdSense
- 百度联盟
- 必应广告 (Microsoft Advertising)
- 自定义 HTML/JS 代码
快速素材生成
后台广告编辑对话框支持快速生成广告素材：
| 素材类型 | 功能说明 |
|---|---|
| 网络图片 | 输入 URL 直接预览，可附带跳转链接 |
| 纯色块 | 颜色选择器 + 自定义文字，自动生成 HTML 代码 |
| 本地图片 | 引用 static/images/ 路径，实时预览，自动补全路径 |
| 纯代码 | 手动粘贴联盟广告 HTML/JS |
所有素材类型均可一键「生成代码」，自动转换为标准广告 HTML。
用户体验设计
- 窄幅不打扰：全局横幅限高 48px，文章内广告限高 90px
- 空容器隐藏：广告位无启用广告时完全不渲染 DOM
- 移动端适配：窄屏自动压缩边距和字体
- 暗色模式全覆盖：所有广告容器和 CSS 变量适配暗色主题
- 关闭按钮：Header 全局横幅支持一键关闭
技术栈
| 层级 | 技术 |
|---|---|
| 数据存储 | TOML (data/ads.toml) |
| 后台 API | Go (Gin) — GET/PUT /api/ads |
| 后台管理 | Vue 3 + Element Plus (border-card Tab 布局) |
| 前台渲染 | Hugo Partial 模板 + 全局 site.Data.ads 函数 |
| CSS | 主题 custom.css 扩展 |
后台管理页 UI
后台广告管理页采用与站点配置一致的 type="border-card" Tab 布局：
- 顶部：全局开关 + 列表广告间隔选择 + 保存按钮
- Tab 栏：9 个广告位标签，每个标签带绿色/灰色圆点指示启用状态
- 右侧内容区：
- 状态栏：广告位名称 + 启用开关 + P0/P1/P2 优先级徽标
- 展示配置：展示模式、轮播间隔、字数阈值等
- 广告列表：卡片式展示每条广告，支持编辑/删除/启用
- 添加按钮：底部添加广告入口
- 编辑对话框集成了快速素材生成功能
文件清单
1data/ads.toml # 广告数据
2admin/backend/internal/handler/ads.go # Go API handler
3admin/frontend/src/views/Ads/Index.vue # Vue 管理页 (border-card Tab)
4themes/.../layouts/partials/ads/
5 ├── render-ad.html # 核心渲染引擎
6 ├── home-banner-below.html # P0-1
7 ├── sidebar-widget.html # P0-2
8 ├── header-below.html # P0-3
9 ├── content-before.html # P1-1
10 ├── content-after.html # P1-2
11 ├── post-bottom.html # P1-3
12 ├── list-between.html # P1-4
13 ├── toc-sidebar.html # P1-5
14 └── footer-above.html # P2-1
15themes/.../assets/js/modules/ads-rotate.js # 轮播脚本
16hugo.toml # widgets.order 新增 advertisement
使用方法
- 启动
admin-server.exe，登录后台 - 侧边栏「系统」→「广告管理」
- 在顶部 Tab 栏选择广告位
- 点击「添加广告代码」，选择素材类型，生成或粘贴代码
- 点击「保存全部」
⚠️ 推送 GitHub 前请按约定清理
hugo.toml中的密码等敏感信息。
留言评论
期待你的想法评论加载中