音乐搜索器 v1.7.8 → v1.8.0：一次“暗黑模式 + 顶部布局 + 弹窗可读性”的前端改造记录

本文按更新日志（2026.03.14 v1.7.8 / 2026.03.17 v1.7.9 / 2026.03.18 v1.8.0）的顺序，记录这套页面在 CSS 变量主题化、暗黑/明亮切换、小屏顶部布局、以及 公告/免责声明弹窗可读性修复 上的关键技术点。

代码栈偏传统：PHP 模板 + AmazeUI 组件 + 一套自定义 style.css。但“主题系统、响应式、可维护 CSS”这些问题，本质上跟框架新旧关系不大。

v1.7.8（2026.03.14）：为“稳定可用”打底

更新日志重点：

• 增加音乐源健康缓存：连续失败自动隐藏
• 修复失效接口，部分接口/示例链接改用 https
• 首页样式与免责声明弹窗重新排版
• 由清幻工作室-毒蛊修改及美化（毒蛊博客：https://blog.idg8.cn/）

1) 健康缓存：把“不稳定”变成“可退化”

多源聚合产品最怕某个源突然抽风导致用户一直点一直失败。健康缓存思路通常是：

• 记录每个源近期失败次数
• 失败达到阈值后“降级/隐藏”该源
• 过一段时间再放出来探活

这类策略本质是把不确定性从用户体验转移到系统策略，避免用户反复踩同一个坑。

2) https 化：减少跳转与拦截

把示例链接/接口改为 https 的好处很直接：

• 浏览器混合内容（HTTPS 页面请求 HTTP 资源）限制更少
• 运营商/中间设备劫持概率更低
• 一些平台对 HTTP 直接 301/302，额外跳转更容易触发风控

v1.7.9（2026.03.17）：主题系统上线（CSS 变量 + 记忆）

更新日志重点：

• 新增：暗黑模式/明亮模式切换（自动记忆用户选择）
• 新增：首页公告弹窗（首次自动弹出，可关闭并记忆）
• 样式：全站基于 CSS 变量，暗黑模式适配更完整

1) 为什么“CSS 变量”是暗黑模式的最小成本方案

相比在每个组件里写两套颜色（.theme-dark ... / .theme-light ...），更可维护的方式是：

• 所有业务样式只用语义变量：--text / --muted / --card / --border ...
• 明亮/暗黑主题只负责给变量赋值

这样你只需要维护：

• 一套结构样式（padding、radius、shadow、布局…）
• 两套变量值（light/dark）

2) 主题“记忆”机制：localStorage 是够用的

这类单页/静态站点的主题记忆，一般就是：

• 点击切换时给 html 加 class（例如 theme-dark）
• 同时把用户选择写入 localStorage
• 下次打开页面初始化时读取并恢复

优点：实现简单、无后端依赖；缺点：不同设备不同浏览器不共享（但多数情况下可接受）。

3) 公告弹窗：一次性展示 + 用户关闭后记忆

“首次访问自动弹出”一般要解决两个问题：

• 如何判断首次？（localStorage 标记）
• 怎么避免每次都弹？（关闭后写标记；需要“手动再打开”的入口）

这也是为什么日志里强调“关闭后记忆；右上角按钮可随时查看”。

v1.8.0（2026.03.18）：移动端顶部布局与弹窗可读性收尾

更新日志重点：

• 优化：手机端顶部区域布局，避免按钮文字被挤成竖排（小屏自动仅显示图标）
• 修复：暗黑模式下公告/免责声明弹窗内容对比度过低导致看不清
• 修复：极小屏幕下顶部“免责声明”按钮文字隐藏后无图标导致显示异常

下面挑两个“看起来很小、但很典型”的前端问题展开。

1) 顶部按钮文字被挤成竖排：如何优雅处理超小屏

问题本质

顶部区域是一个横向按钮组：主题 / 公告 / 免责声明。

小屏宽度不足时，常见现象：

• 文本被挤压换行
• 在某些布局/字体渲染下，甚至出现“逐字竖排”的灾难效果

解决思路

• 按钮本身用 inline-flex 布局
• 强制不换行：white-space: nowrap;
• 对极小屏做响应式降级：隐藏文字，仅保留图标（信息密度更高）

这类处理背后的原则是：

小屏不是要“完整展示所有信息”，而是要“用最小空间表达可用的交互”。

2) 暗黑模式下弹窗内容对比度过低：用作用域 + inherit 统一正文颜色

问题复现（典型）

AmazeUI 的弹窗、列表、strong、a 等元素可能自带默认颜色；而项目自身又有主题变量。

当这些规则叠加时，暗黑模式下很容易出现：

• 正文颜色偏灰、背景偏暗 → 对比度低
• 某些子元素（li / strong / a）被框架样式覆盖 → 颜色不统一

关键结论

与其在每段公告/免责声明文案上手动加 class，不如把“颜色规则”放到容器层：

• 容器（.am-popup-bd）决定主题色
• 子元素统一 inherit

这样你以后怎么改文案、换成什么标签，颜色都稳定。

代码实现（节选）

弹窗 DOM 的关键点是：正文都在 .am-popup-bd，且两个弹窗有独立 ID：

• #site-notice（公告）
• #copr-info（免责声明）

因此我们只对这两个弹窗的正文做“作用域内强制”：

/* 公告/免责声明弹窗：内容文字固定蓝色（后续你改内容也默认蓝色） */
#site-notice .am-popup-bd,
#copr-info .am-popup-bd {
  color: #2563eb !important; /* blue-600 */
}

html.theme-dark #site-notice .am-popup-bd,
html.theme-dark #copr-info .am-popup-bd {
  color: #60a5fa !important; /* blue-400 */
}

/* 强制正文内所有元素跟随弹窗正文颜色 */
#site-notice .am-popup-bd *,
#copr-info .am-popup-bd * {
  color: inherit !important;
}

另外，免责声明正文用的是 ul.disclaimer，原本可能有单独的 li/strong 颜色。为了不“抢颜色”，把它们也改成继承：

.disclaimer li {
  color: inherit !important;
}

.disclaimer strong {
  color: inherit !important;
  font-weight: 700;
}

为什么这里允许使用 !important

工程上不是不能用 !important，而是不要无脑全局用。

本例里满足三个条件：

1. 作用域很小：只在 #site-notice / #copr-info 两个弹窗内
2. 目标明确：弹窗正文可读性优先级高于框架默认
3. 可维护：通过 inherit，未来文案结构改动也不需要额外补 CSS

这类场景用 !important 反而是“稳定且成本最低”的方案。

小结：这次更新解决了哪些“长期会被反复踩的坑”

把 v1.7.8～v1.8.0 放在一起看，会发现它们其实在做同一件事：

• 功能层面：多源聚合的不稳定，用缓存策略兜底
• 体验层面：主题切换 + 记忆，减少用户反复设置
• 可用性层面：小屏布局降级，避免 UI 崩坏
• 可读性层面：暗黑模式弹窗对比度修复，保证关键说明可读

如果要用一句话概括这段演进：

不追求“花哨的炫技”，而是把 UI/交互最容易出问题的细节逐个补齐，让产品在不同设备/主题/不稳定外部环境下都能更稳地跑起来。