项目：t1mmoc.github.io（Hugo + PaperMod，GitHub Pages 部署） 范围：本日博客美化包含头像重做、友链页、Giscus 评论、首页改版与全站背景；本文聚焦最新上线的全站二次元背景改版。 状态：已上线（特性分支 → no-ff merge → push main → GitHub Actions 自动部署）。

0. 目标

给博客加全站二次元随机背景，同时满足三个硬约束：

  1. 文章流可读：背景不能糊住文字（不花眼）
  2. 流量克制：随机图不能让访客每次刷新都爆流量
  3. 深浅色自适应：深色/浅色模式都舒服

1. 图源选型

先批量探测了十几个免费二次元图源，多数已死或防盗链。后端实测存活 6 个：

源类型延迟备注
t.alcy.cc重定向1.5s稳，保底可用
uapis.cn重定向1.5s?category=acg，用户选定
yeqing.net重定向1.2s最快
dujin.org重定向3.0s稳
dmoe.cc重定向8.9s偏慢
lie.moe重定向5.9s弱，仅部分成功

已淘汰（源挂/防盗链）：Lolicon、waifu.pics、anosu、vvhan、xiaowon、sretna、img.xjh.me、acg.yanwz.cn 等。

最终选定 uapis.cn（https://uapis.cn/api/v1/random/image?category=acg）：302 重定向到 CDN 直链（https://uapis.cn/assets/acg/pc/xxx.jpg），无防盗链，只需 referrerpolicy="no-referrer" 即可直链加载。

2. 可读性方案（三层结构）

背景层  body::before      固定铺满、清晰不模糊、两侧无遮罩（露出背景）
内容区  .post-entry 等    半透明 + backdrop-filter 毛玻璃，只模糊卡片背后的背景
兜底    纯色 --theme       图未加载时不白屏
  • 两侧空白区背景清晰锐利（不做模糊/遮罩）
  • 中间文章卡片做毛玻璃：浅色偏白 0.92、深色偏深 0.84；单篇文章页浅色更低 0.72（更明显透出背景）
  • 模糊 14px，卡片 16px 大圆角

3. 缓存与流量克制机制（核心）

四层叠加，目标「不花眼、不爆流量、切页不换图」：

  1. 图池内置（建站即下发） 后端预抓 38 张 uapis.cn 真实 CDN 直链，写死在页面 POOL 数组里。运行时完全不请求 API 网关，只在池内选。

  2. localStorage 固定 24h（防切页换图） 首次进站从池里随机选 1 张，存 localStorage（tmoc_bg_url + tmoc_bg_ts）。之后切页/刷新只要未超 24h 就复用同一张，不发新请求。

  3. 「换背景」按钮限频 右下角「换背景 ❤」按钮：每次点击 2.5s 冷却 + 每天最多 12 次（tmoc_bg_cnt + tmoc_bg_date，跨天清零），超出提示「今日已达上限」。换图从池内随机挑（避开当前张），预加载成功才落盘。

  4. 浏览器 CDN 缓存 图片是 CDN 直链，自带 Cache-Control: max-age=604800（7 天），同一张图浏览器再缓存 7 天字节，二次加载零流量。

流量账：普通浏览每人每 24h 最多下载 1 张新图；主动换图每天 ≤ 12 张；源挂了回退纯色不白屏。

4. 关键踩坑与根治

问题根因修复
浏览器全裂图源防盗链（referer 校验）<meta name="referrer" content="no-referrer"> + JS img.referrerPolicy 双保险
切页/刷新自动换图（缓存失效）uapis.cn 无 CORS 头，前端拿不到 302 后的真实地址，缓存的是 API 地址本身（每次随机重定向）后端预抓 38 张真实直链内置图池，首次池内选一张固定 24h
预览里点文章跳线上index.html 用 .Permalink（绝对地址带死 baseURL）改 .RelPermalink（相对链接），预览服务指定 baseURL，点哪留哪
深色模式头像白边PaperMod 无 --background 变量（页面底色叫 --theme）改用 --theme；CSS 走 Hugo fingerprint 防旧缓存
首屏瞬态白边auto 主题 JS 解析前无变量定义回退浅色补 :root[data-theme="auto"] 的 --theme + prefers-color-scheme:dark 媒体查询

5. 首页 hero 改造

  • 删除头图 banner
  • 头像 + 站点名 + 描述整体包进一张毛玻璃卡片（.site-hero__card）
  • 头像 92px、左对齐 align-items:center（垂直居中）、描述 1.05rem、卡片宽度 = container（与文章同宽）
  • 移动端左对齐、头像 72px

6. 上线

git checkout -b workbuddy/hero-bg-deploy
git add assets/css/custom.css layouts/_partials/* layouts/index.html layouts/partials/site_hero.html
git commit -m "全站二次元背景：uapis.cn 图池 + 毛玻璃 + 24h缓存 + 换背景按钮 + hero 头像卡片"
git checkout main
git merge --no-ff workbuddy/hero-bg-deploy -m "merge: 全站二次元背景与首页 hero 改版上线"
git push origin main        # GitHub Actions 自动构建部署

改动文件：

  • assets/css/custom.css — 背景层、毛玻璃、hero 卡片、深浅色变量
  • layouts/_partials/extend_footer.html — 图池 + 缓存 + 换背景按钮（新增）
  • layouts/_partials/extend_head.html — no-referrer meta
  • layouts/index.html — 相对链接
  • layouts/partials/site_hero.html — 头像卡片结构

7. 可复用经验

  1. 给用户看 Hugo 草稿，只用本地相对链接预览（预览服务指定 baseURL 让主题链接也留本地），绝不要拿生产站 URL 当预览。
  2. 图源连通性以用户浏览器为准——沙箱网络受限会误判"源不可用"。
  3. 改 PaperMod 主题依赖的 CSS 变量，用其内置名（--theme/--entry/--primary/--secondary/--border），别自造。
  4. 外链 CSS 一律走 resources.Get | minify | fingerprint，内容一变 URL 即变，杜绝旧缓存。
  5. 无 CORS 的随机图 API，根治"切页换图"是后端预抓直链内置图池，而非前端 fetch 重定向地址。