From c1b08ad915b20b605961340773add65f7b4a9e5a Mon Sep 17 00:00:00 2001 From: nxxy335 Date: Sun, 27 Sep 2026 17:49:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E3=80=8C=E5=8D=87?= =?UTF-8?q?=E7=BA=A7=E5=90=8E=E9=83=A8=E5=88=86=E9=A1=B5=E9=9D=A2=E9=85=8D?= =?UTF-8?q?=E8=89=B2=E4=B8=8D=E7=94=9F=E6=95=88=E3=80=8D=E6=8E=92=E6=9F=A5?= =?UTF-8?q?=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根因为「页面静态缓存」插件只随文章变更刷新缓存，主题升级/设置变更 不会失效，旧 HTML 停留在 v1.1.x（无 data-palette、旧 CSS）。 FAQ 新增专项条目与清缓存步骤；README 安装节加指引；changelog 补记。 --- README.md | 4 ++++ docs/changelog.md | 15 +++++++++++++++ docs/faq.md | 28 ++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+) diff --git a/README.md b/README.md index a6d2911..10e0472 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,10 @@ > 它引用的 CSS 文件名带内容哈希，升级后已被删除，请求会直接 500。 > 先在 Halo 后台执行一次「清理缓存」（并刷新 CDN / Nginx 缓存）即可。 > 主题从 v1.2.1 起会把历史版本的哈希资源一并发进安装包，旧 HTML 也不会请求失败。 +> +> **升级主题或修改配色后，部分页面不生效**：如果安装了「页面静态缓存」插件， +> 它只随文章变更自动刷新，主题层的变更需要手动点一次「刷新页面缓存」， +> 详见 [FAQ：升级主题或修改配色后部分页面不生效](docs/faq.md#升级主题或修改配色后部分页面的新样式配色不生效)。 或从源码构建： diff --git a/docs/changelog.md b/docs/changelog.md index 5799c82..887d5ab 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -18,6 +18,21 @@ - 🧰 新增构建脚本：`pnpm snapshot`（历史资源快照）、`pnpm package`（打安装包）、`pnpm smoke`（点击特效冒烟测试） +### 补充排查记录：升级后部分页面配色/新样式不生效 + +上线后收到反馈：更换主题配色后，**首页与瞬间页不跟随**，其他页面正常。经排查 +（对比浏览器实际加载的资源、CDP 读取计算样式、比对响应头）确认： + +- 浏览器拿到的首页/瞬间 HTML 是 **v1.1.11 / v1.1.12 时期**的旧页面（引用旧哈希 CSS、 + `` 上没有 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 ### 主题配色系统 diff --git a/docs/faq.md b/docs/faq.md index b33b735..998d972 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -42,6 +42,34 @@ Halo 找不到文件时会返回 **500**（日志里能看到 `FileNotFoundExcep v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖）， 即使缓存里的旧 HTML 被再次请求也不会 500，但最终仍建议清一次缓存以使用最新样式。 +### 升级主题或修改配色后，部分页面的新样式/配色不生效？ + +先说结论：**这不是主题问题，是「页面静态缓存」插件缓存了旧版 HTML。** + +排查特征（本站实际案例）： + +- 换了主题配色，首页和瞬间页永远是默认配色，其他页面正常 +- 用 `curl` 直接请求同一个 URL 却能拿到新 HTML（极具迷惑性——缓存插件对 + 非浏览器请求会绕过缓存，所以服务端"看起来"一切正常） +- 响应头里有 `X-Halo-Cache-At` 和 `Cache-Control: max-age=3, s-maxage=120, must-revalidate` + —— 这是「页面静态缓存」插件的特征头，`X-Halo-Cache-At` 就是缓存写入时间 +- 浏览器里页面引用的主题 CSS 还是旧版本的哈希文件名 + +原因：「页面静态缓存」插件**只监听文章内容的变动**自动刷新缓存， +**主题升级、主题设置（配色、Hero、样式等）变更都不会刷新缓存**。 +缓存里的旧 HTML 是旧版本主题渲染的：没有新版的配色属性、引用的还是旧 CSS， +所以新功能在那些页面上永远不出现，直到缓存被清理或被新访问覆盖。 + +处理步骤： + +1. Halo 后台 → 仪表盘 → 快捷访问 → 添加「**刷新页面缓存**」入口 → 点击清理一次 +2. 浏览器强制刷新（Ctrl+Shift+R） +3. 如果配了 CDN（插件会给已缓存页面发 `s-maxage=120`），确认 CDN 缓存策略为 + **遵循源站**，这样 CDN 最多 2 分钟就会回源，无需手动刷新 + +**长期建议**：以后每次**升级主题或修改主题设置**后，都点一次「刷新页面缓存」， +否则未登录访客最长会一直看到旧页面（插件不会自动感知主题层的变更）。 + ## 功能相关 ### 鼠标点击效果 / 拖尾效果开启了却没反应？