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、
+  `<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
 
 ### 主题配色系统
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 分钟就会回源，无需手动刷新
+
+**长期建议**：以后每次**升级主题或修改主题设置**后，都点一次「刷新页面缓存」，
+否则未登录访客最长会一直看到旧页面（插件不会自动感知主题层的变更）。
+
 ## 功能相关
 
 ### 鼠标点击效果 / 拖尾效果开启了却没反应？