halo-theme-WarmIsland/docs/changelog.md

# 更新日志

## v1.2.7

### 文档全面校准（与最新版主题对齐）

- 🔌 **移除「朋友圈」插件的全部使用说明**：`plugin-friends` 已不再提供，原先的 feed / RSS 聚合能力
  由官方 **「链接管理」（PluginLinks）插件的订阅**承担。主题的对应实现是 `page_subscriptions.html`
  自定义模板与 `subscriptions` 设置分组；新增订阅配置 / 订阅页面文档，删除旧的朋友圈配置与页面文档
- 📌 主题保留 `friends.html` 模板与「朋友圈」设置分组**仅用于兼容旧站点**，`pluginFinder` 检测不到
  该插件时会显示空状态；新站点请勿再依赖，文档已明确标注
- ⬆️ 全文统一 Halo 版本要求为 **2.27.0+**（`docs/guide/getting-started.md` 原写 `2.24.0`，与
  `theme.yaml` 的 `requires: ">=2.27.0"` 不一致）
- 🧹 清理与代码不符的描述：已移除的光感跟随 `animation_cursor_glow`、主题并不自带的
  i18n 国际化、没有对应模板的「足迹页面」；`docs/config/style.md` 补上实际存在的
  `click_effect_enabled` / `click_effect_type`
- 📚 补齐此前完全没有文档的三个设置分组：**欢迎弹窗、订阅、微信读书**；自定义页面模板清单
  同步为 4 个（默认 / 留言板 / 订阅 / 微信读书）
- 🔢 配置数量统一为 **17 组 / 126 项**，插件适配表按实际 **10 款**校准，VitePress 侧边栏同步调整
- 🔗 所有文档内部相对链接复核为 0 处失效
- 🧾 README 精简与重排：移除开发者自证、回归检查清单与重复的「不加载远程脚本」类宣言，
  按「安装 → 功能 → 插件 → 隐私 → 开发 → 声明」重排章节（331 行 → 237 行）；
  5.1 逐项披露、许可表与原创声明完整保留

### 可选 API 设置项文案精简

- ✂️ 主题设置中「自定义 IP 定位主 API」「自定义 IP 定位备选 API」「自定义一言 API」
  三个配置项的 `help` 移除三段冗长的隐私披露文案，仅保留功能说明（候选接口地址、留空回退规则）
- 🛡️ 第三方数据流向与隐私披露仍由 README「外部资源与隐私」章节、配置文档与 FAQ 完整承载，
  满足 5.1 要求；设置界面文案精简不影响「默认零第三方请求」的结论
- ↩️ 三个字段恢复按功能开关条件显示（「启用欢迎弹窗」开关 / 「描述文案来源」），与 v1.2.6
  的设计一致；同时修正三个配置块的缩进，与 `settings.yaml` 其余字段对齐
- 🔒 `pnpm audit:external` 的 5.1 检查改为：三个字段必须存在、`help` 不得回潮出现披露文案、
  README 必须保留隐私披露章节

### 正文引用块留白（与上一轮改动合并）

- 🎨 修复文章 / 单页 / 留言板正文引用块文字下方空白过大：块内元素外边距与 `padding` 叠加导致
  双层留白，现统一收敛，并折叠编辑器生成的空段落；引用块上下外边距同步收紧

## v1.2.6

> v1.2.5 为审核被拒的未发布版本，从未对外分发；其全部整改内容纳入 v1.2.6 一并发布。
> 上一个对外发布版本为 v1.1.1（v1.1.2 – v1.2.5 均未发布）。

### 本轮变更

- 🆙 版本号升至 `1.2.6`，与上次被拒的审核快照明确区分
- ✍️ 新增「原创声明（4.2.1）」：本主题完全原创，未基于任何已有主题 / 插件派生，4.2.1 / 4.2.2 不适用
- 🔇 Hero「描述文案来源」默认值由 `hitokoto` 改为 **`none`** —— 默认不渲染一言元素、不显示描述文案，零外部请求
- 🔗 选择「一言」时自动填入官方接口 `https://v1.hitokoto.cn/`；选择「一言」或「自定义」后若 API 留空，
  则使用主题内置的本地句子库（零外部请求）。**只有填写后才会向该地址发起请求**，需自行在站点隐私说明中披露，
  详见 README「外部资源与隐私」
- 🌐 文档列出两个可选 IP 定位接口：`https://myip.ipip.net/json` 与
  `https://r.inews.qq.com/api/ip2city?otype=json`（主 / 备选 API 均可选用）。
  **填写后会把访客 IP 发送给该第三方服务换取地理位置**，需自行在站点隐私说明中披露，
  详见 README「外部资源与隐私」
- 📄 README「外部资源与隐私」新增可选接口清单与逐项披露；docs 的 Hero 配置、FAQ、快速开始与首页页同步更新

### 上架审核整改（原 v1.2.5 修订，并入 1.2.6）

- 🔒 **默认零第三方自动请求**：移除全部 21 个模板对 `cdn.jsdelivr.net` 的 `preconnect` / `dns-prefetch`
- 🔒 移除文章页 PrismJS 1.29.0、`autoloader`（会按代码语言从 CDN 动态拉取并执行组件）与
  `qrcode-generator`；代码高亮改由应用市场代码高亮插件 / API 扩展包提供，主题只保留自托管的
  Warm / Cold token 配色（微信分享改为「复制链接」）
- 🔒 一言默认改用内置本地句子库 `assets/data/hitokoto.json`，不再默认请求 `v1.hitokoto.cn`
- 🔒 欢迎弹窗默认显示本地静态欢迎语，移除内置的 IP 定位主 / 备选第三方接口；IP 定位改为
  **管理员显式配置**的可选能力（开启时会向该服务发送访客 IP，需自行披露）
- 📄 README 新增「外部资源与隐私」章节（服务名称 / 用途 / 数据类型 / 默认状态 / 关闭方法 /
  遥测声明）与「验证与回归测试」清单；补充 LXGW WenKai 的 OFL 来源与 LightGallery GPLv3 说明
- 🔗 修正上架说明中的无效链接：文档与预览图改为有效绝对地址并随包分发；朋友圈插件链接改为应用市场地址
- 🐛 全部 `#strings.substring(..., 0, 1)` 增加空值保护，修复 `friends.html` 作者为空时的字符串越界
- 🖼️ `logo.png` 由两份 1024×1024（各约 1.5MB）压缩去重为单份 256×256（约 146KB）
- ✅ LightGallery 去掉占位 `licenseKey`，按 GPLv3 开源许可使用，控制台不再出现授权提示
- 🧪 新增 `pnpm audit:external` 与打包前置校验：拦截第三方远程加载、预连接、动态加载、
  README 死链、重复大图；`docs/*.md` 与预览图一并打进安装包

#### 按 v2026.09.07 审核指南全文补充自查（并入 1.2.6）

- 🔒 **内容渲染安全（4.4.2）**：文章页 JSON-LD 不再用 `th:utext` 把标题 / 摘要 / 作者 / 封面
  拼进 `<script>` 原始文本（可被脚本闭合标签截断并注入）；改为「Thymeleaf 转义写入 `<meta>`
  → `JSON.stringify` → `textContent`」，并新增 `<meta name="author">`。瞬间正文 `content.raw`
  兜底从 `th:utext` 改为 `th:text` 转义输出（首页区块、瞬间页列表 / 瀑布流、详情页共 4 处）
- 📜 **许可证传递（5.2）**：`public/assets/fonts/LXGWWenKai/OFL.txt` 随包携带上游版权声明、
  保留字体名附加许可与 SIL OFL 1.1 全文；`pnpm build` / `pnpm package` 均校验其存在与内容
- 🔢 **上架信息校准（2.2 / 4.6）**：README 设置项按 `settings.yaml` 实测改为 17 组 / 126 项、
  点击特效改为 8 种效果（可关闭）；新增「内容渲染安全」章节与搜索页 / 空结果状态人工回归项
- 🧪 合规审计扩展：拦截任意 `<script>` 上的 `th:utext`、缺失字体许可证、README 数字漂移；
  `pnpm smoke` 新增 JSON-LD 合法性与注入防护的桩 DOM 验证

### 兼容性与元数据

- ⬆️ Halo 版本要求提升至 **2.27.0+**（页面布局契约、微信读书页面依赖 2.27 的能力）
- 🔗 源码仓库与问题反馈地址统一为 `https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland`
- 📚 完善安装、开发、FAQ 文档，修正过时的技术栈与构建打包说明

### 性能优化

- 🚀 **首页滚动顺滑性**：移除逐帧改写全屏 `backdrop-filter` 模糊半径的逻辑。
  旧实现让 Chromium 每个滚动帧都重做一次全屏背景采样 + 高斯模糊，是首页掉帧主因；
  现改为固定模糊半径 + 只调整 `opacity`（合成层操作），并缓存进度值避免重复写 DOM
- 🚀 **首屏离屏即停**：滚过首屏后 Hero 已被不透明内容区完全盖住，此时隐藏 Hero
  并暂停光球动画，长页面后半段不再有额外绘制
- 🚀 **首屏整屏吸附回归（顺滑版）**：v1.2.5 初版改用 CSS `scroll-snap: y proximity` 后吸附
  实际失效——内容区顶部是唯一吸附点、页面顶部 `0` 没有吸附点，`proximity` 几乎不触发；
  换成 `mandatory` 又会把长内容反复拉回内容区顶部。现改为**边界吸附**：只在
  `0 ↔ 内容区顶部` 接管一次滚轮 / 触摸，进入内容区后完全交给原生滚动惯性；解锁用
  `scrollend` + 600ms 兜底（原为固定 800ms 输入锁），已在目标位置时不再接管
- 🚀 **导航栏滚动状态去重**：只在状态真正变化时写 class，不再每帧触发样式重算
- ♿ 补充 `prefers-reduced-motion` 支持：减少动态效果时关闭平滑滚动与光球 / 指示箭头动画，
  吸附改为即时定位（不再关闭吸附）
- 🖼️ 首页文章列表继续使用 `content-visibility: auto` 跳过视口外渲染，图片保持懒加载

## v1.2.4

### 问题修复

- 🐛 **彻底修复首页页脚被 Hero 盖住（v1.2.3 的修复不完整）**：仅取消 main 的
  层叠上下文（`z-index: auto`）不足以让固定 Hero 稳定落在页脚之下。现改为
  **双保险**：
  1. `.hero` 由 `z-index: 0` 改为 `z-index: -1`，作为固定全屏背景沉到根层叠
     上下文的负 z 层，绘制在一切正常内容（含页脚）之下——这是固定背景的规范做法；
  2. 保留首页 main `z-index: auto`（仍是必须项：否则 main 若保持 `z-index: 1`
     会成为层叠上下文，把负 z 的 Hero 困在自己内部、整块仍压在页脚之上）。
  页脚因此始终保持无 z-index 的状态，既不会被 Hero 盖住，也不会回退到早期
  「页脚盖住评论区翻页下拉」的问题。经无头浏览器在真实构建产物上验证：
  滚到页底时 `elementFromPoint` 命中 `footer-inner`，页脚完整可见。

## v1.2.3

### 问题修复

- 🐛 **初步修复首页页脚被 Hero 盖住（不完整，已被 v1.2.4 取代）**：取消首页
  main 的层叠上下文（`z-index: auto`）。这一项单独作用时仍不够稳健，
  请直接参考 v1.2.4 的完整修复。

## v1.2.2

### 问题修复

- 🐛 **修复移动端抽屉菜单不显示二级菜单**：子菜单的 `th:block` 写在了 `th:each` 循环外，
  循环变量出了循环即失效，二级菜单从未渲染过；现在子菜单与父项一起循环输出
- 🐛 **修复页脚遮挡内容弹层**：页脚的 `z-index: 1` 与内容区同级且靠后，
  会盖住评论区翻页下拉等浮层；同时把 `.wi-main` / `.wi-content-wrap` 的
  `overflow-x: hidden` 改为 `clip`，不再产生会纵向裁掉弹层的滚动容器
- 🐛 **修复深浅色切换不同步**：页脚背景是渐变（`background-image`），
  无法参与过渡动画，切换时页脚瞬变而内容区还在 300ms 渐变；
  改为可过渡的 `background-color` + 遮罩渐隐色层，全站同步过渡
- 🐛 **修复玻璃卡片悬浮时顶部边框消失**：Chromium 下带 `backdrop-filter` 的元素
  一旦发生位移（悬浮上移），合成层会吃掉顶部 1px 边框。已移除瞬间、友链页、
  友链圈、订阅页卡片的 `backdrop-filter`（卡片背后是纯页面背景，模糊无可见效果），
  并给瞬间卡片悬浮时加描边高亮

### 功能与优化

- 🎨 **新增瞬间详情页主题化模板**（`moment.html`）：覆盖插件默认模板，
  复用瞬间列表页的卡片视觉（头像 + 昵称 + 时间 + 正文 + 九宫格 + 点赞），
  评论区默认展开，附返回列表入口与空态兜底；支持灯箱看图
- 🎨 **Steam 游戏库页**：统计数据加载失败时不再整块隐藏，改为显示 `-` 并给出
  原因提示（Steam 接口超时 / 游戏库隐私 / 插件配置）；「最近游玩」卡片成就进度
  移到右侧并增加奖杯标识

## v1.2.1

### 问题修复

- 🐛 **修复升级后整站没有样式**：Astro 会给 CSS/JS 加内容哈希，升级后旧文件被删除，被缓存的 HTML 仍请求旧文件名，
  Halo 直接抛 `FileNotFoundException` 返回 500，样式全部丢失。主题现在会把各版本的哈希资源一并保留
  （`compat/assets` 在构建时合并进 `templates/assets`，已覆盖 v1.1.7 起的所有版本）
- 🐛 **避免页面出现 500**：新增构建期静态资源引用校验，模板引用的任一缺失资源都会让构建失败
- 🐛 **修复鼠标点击效果开启后没有任何作用**：旧实现用 `th:if` 判断开关、且直接读取配置值，
  一旦配置项未随版本写入（或被 Thymeleaf 整体移除属性）就读取为空，脚本直接跳过；
  同时修复了多种特效在插入节点后随即改写 `transform` / `opacity`，导致浏览器把初态与终态合并、
  transition 完全不触发的问题（表现为点了没反应）
- 🐛 次要修复：点击特效节点统一挂载到 `body` 下的独立图层（`z-index: 12050`），不再被导航栏、页脚遮挡

### 其他

- 🧰 新增构建脚本：`pnpm snapshot`（历史资源快照）、`pnpm package`（打安装包）、`pnpm smoke`（点击特效冒烟测试）

### 补充排查记录：升级后部分页面配色/新样式不生效

上线后收到反馈：更换主题配色后，**首页与瞬间页不跟随**，其他页面正常。经排查
（对比浏览器实际加载的资源、CDP 读取计算样式、比对响应头）确认：

- 浏览器拿到的首页/瞬间 HTML 是 **v1.1.11 / v1.1.12 时期**的旧页面（引用旧哈希 CSS、
  `<html>` 上没有 v1.2.0 新增的 `data-palette` 属性）
- 响应头 `X-Halo-Cache-At` 与 `Cache-Control: max-age=3, s-maxage=120` 表明这些页面
  被 **「页面静态缓存」插件** 缓存，而该插件只随文章变更自动刷新，
  **主题升级 / 主题设置变更不会刷新缓存**
- 裸 `curl`（无浏览器请求头）会绕过该缓存拿到新 HTML，因此服务端"看起来"一切正常

这是缓存层行为、不是主题缺陷，**在 Halo 后台点一次「刷新页面缓存」即可**；
排查步骤已写入 [FAQ](faq.md#升级主题或修改配色后部分页面的新样式配色不生效)。

## v1.2.0

### 主题配色系统

- ✨ 新增「主题配色」设置（总体样式 → 主题配色），内置 11 套官方预调配色：暖屿·赤陶（默认）、抹茶、黛蓝、樱粉、暮紫、海盐、琥珀、梅酒、石墨、可拿铁、天青
- 🎨 每套配色包含浅色 / 深色两套完整色板，玻璃拟态、遮罩、阴影色调自动跟随当前配色
- 🎨 自定义「强调色」改为留空跟随所选配色；填写后仍可单独覆盖
- 📱 浏览器地址栏 theme-color 随配色与明暗模式联动（含切换按钮）

### Hero 首屏

- ✨ 一言文字新增独立颜色配置（浅色 / 深色模式各一项，此前只能跟随副标题颜色）
- ✨ 新增「文字显示效果」设置：阴影 / 光晕 / 半透明遮罩层 / 渐变遮罩 / 容器（半透明边框圆角矩形 + 加大留白）
- 🐛 默认改为无任何效果：移除标题、副标题与一言自带的白色散光投影

### 问题修复

- 🐛 修复 /douban 页面 500：适配豆瓣插件 v1.2.6 的 SQLite 数据结构（字段由 `item.spec.*` / `item.faves.*` 扁平化为 `item.*` / `item.faves*`）
- 🐛 修复友情链接卡片悬浮光圈被裁切的问题（卡片容器不再裁切悬浮阴影与上移位移）
- 🐛 修复瞬间页面顶图与最新一条瞬间卡片的边框贴合的问题，顶图下方增加间距
- 🐛 友情链接卡片徽章简化为仅展示站点可达性（绿点 = 可访问，红点 = 异常），不再联合反链检测结果判断

### 其他

- ⬆️ Halo 版本要求提升至 **2.26+**

## v1.1.1

### 瞬间页面

- 🗑️ 移除时间轴（Timeline）布局，简化为卡片（Cards）和瀑布流（Masonry）两种样式
- 🎨 卡片样式成为新的默认展示样式，采用一栏式居中布局
- 🧹 清理时间轴相关的 HTML、CSS 和 JS 代码

### 移动端阅读体验优化

- 📱 全面增大移动端字体尺寸，提升文章阅读舒适度
- 📱 优化文章正文行高（1.75 → 1.8），段落间距更宽松
- 📱 移动端标题字号适配（h2/h3/h4 在 768px 以下适当放大）
- 📱 优化全局排版变量（text-xs ~ text-5xl 基准值上调）
- 📱 优化引用块、代码块、表格在移动端的显示
- 📱 优化文章卡片在移动端的标题和摘要字号
- 📱 优化瞬间页面卡片在移动端的文字和间距

### 导航修复

- 🐛 修复导航菜单 target 属性渲染错误，导致部分链接在新标签页打开的问题
- 🐛 修复 Halo 菜单项 `spec.target` 枚举对象解析为 `target="null"` 的问题

### 错误处理增强

- 🛡️ 添加全局 unhandledrejection 捕获，抑制浏览器扩展产生的控制台错误
- 🛡️ 复制链接按钮添加 clipboard API 失败回退逻辑
- 🛡️ Logo 图片加载失败时自动隐藏并显示站点标题

## v1.1.0

### 分享功能增强

- ✨ 新增 QQ 分享按钮（Font Awesome 图标）
- ✨ 新增微信扫码分享（二维码弹窗）
- ✨ 新增分享渠道配置项，可自由选择显示哪些分享按钮
- 📋 复制链接按钮始终显示，不可关闭
- 🎨 各分享按钮独立品牌色 hover 效果（QQ 蓝、微信绿、微博红等）
- 🌐 i18n 国际化支持新增 QQ、微信、微信扫码相关翻译

### 移动端优化

- 📱 修复文章上下篇导航在移动端分成两行的问题，改为单行省略截断
- 📱 修复目录悬浮球按钮位置偏上，调整到右下角更合理位置
- 📱 优化移动端灯箱体验：增大导航按钮触摸区域、小屏隐藏 EXIF 信息
- 📱 优化移动端分享按钮触摸目标大小

### 灯箱优化

- 🖼️ 修复关闭画廊后 lg-sub-html 不跟随到底部的问题
- 🖼️ 修复打开画廊时 lg-sub-html 和 lg-inner 直接跳位而非平滑过渡的问题
- 🖼️ 优化移动端灯箱导航按钮和缩略图栏布局
- 🖼️ 小屏幕下隐藏 EXIF 参数信息，简化界面

### 分享修复

- 🐛 修复微信扫码分享 QR 码生成相对路径而非完整 URL 的问题
- 🐛 修复复制链接按钮复制相对路径而非完整 URL 的问题
- 🐛 修复 QQ 分享链接不可用，改为弹窗分享方式并正确编码 URL

### 性能优化

- ⚡ 添加 content-visibility 优化（首页、文章、归档、瞬间等区域）
- ⚡ Prism.js 脚本延迟加载
- ⚡ LightGallery 初始化改用 requestIdleCallback
- ⚡ 封面图优先加载（loading="eager"）
- ⚡ 正文图片自动添加 lazy loading
- ⚡ 微信二维码 QR 码库按需加载（仅微信分享启用时加载）

### 全局优化

- 🎨 添加 theme-color meta 标签，适配移动端浏览器地址栏颜色
- 🎨 主题切换时动态更新 theme-color
- 🛡️ 多层 overflow-x: hidden 防止横向滚动条
- 📱 移动端搜索按钮不再隐藏

### 布局修复

- 📐 恢复文章详情页为 800px 全宽布局（不使用 wide 模式）
- 📐 封面图在 800px 容器内显示

## v1.0.0

首次发布 🎉

### 核心功能

- 🎨 暖色调设计语言，呼吸动效光球、毛玻璃导航栏
- 🌙 深色模式支持（跟随系统 / 浅色 / 深色三种方案）
- 📱 响应式布局，移动端专属菜单与交互体验
- ✨ 滚动渐入动画、光感跟随效果

### SEO 与结构化数据

- 🔍 Open Graph 元标签，优化社交媒体分享预览
- 📋 JSON-LD 结构化数据，提升搜索引擎理解与展示

### 国际化

- 🌐 i18n 国际化支持（简体中文、繁体中文、英语）
- 🔄 跟随浏览器语言自动匹配，也可手动指定
- 🍪 支持通过后台设置强制指定语言，自动管理 language cookie

### 文章页增强

- 📑 目录展开模式选项（仅展开当前分组 / 全部展开）
- 📰 相关文章推荐，帮助读者发现更多内容
- 🔗 分享功能（微博 / X / Facebook / Telegram / 复制链接）
- 🖼️ 图片懒加载 blur-up 效果，优化加载体验

### 页面模板

- 🏠 Hero 首屏（一言 API / 自定义描述 / 背景图片）
- 📝 文章详情页（侧边目录 / 阅读进度条 / 代码高亮 / 图片灯箱 / 点赞）
- 📂 归档页面（时间线布局）
- 🏷️ 分类和标签页面
- 💡 瞬间页面（Timeline / Cards / Masonry 三种样式）
- 📷 图库页面（Masonry / Grid / Carousel 三种样式）
- 🔗 友情链接页面（Cards / Grid / List 三种样式）
- 👥 朋友圈页面
- 💬 留言板自定义模板
- 📦 扩展页面支持（豆瓣 / 装备 / Steam）

### 导航与交互

- 🔍 搜索集成（支持 Ctrl+K 快捷键）
- 🎯 三种导航栏样式（Glass / Minimal / Float）
- 🌓 主题切换按钮

### 性能与体验

- ⚡ preconnect / dns-prefetch 资源提示，优化外部资源加载
- 🖼️ 图片懒加载 blur-up 渐显效果
- 🔤 使用系统默认字体栈，提升加载速度

### 错误页面

- 🐘 404 / 500 错误页增强（导航栏 + 页脚 + 多语言支持）

### 配置与自定义

- ⚙️ 丰富的主题设置面板（13 个配置分组）
- 🎨 可自定义强调色、圆角风格、容器宽度
- 📝 自定义 CSS 支持
- 🔧 页脚社交链接和自定义 HTML