nxxy335/halo-theme-WarmIsland
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
c1b08ad915b20b605961340773add65f7b4a9e5a
halo-theme-WarmIsland/docs/faq.md
T
nxxy335 c1b08ad915 docs: 补充「升级后部分页面配色不生效」排查记录 
根因为「页面静态缓存」插件只随文章变更刷新缓存，主题升级/设置变更
不会失效，旧 HTML 停留在 v1.1.x（无 data-palette、旧 CSS）。
FAQ 新增专项条目与清缓存步骤；README 安装节加指引；changelog 补记。
2026-09-27 17:49:34 +08:00

6.4 KiB
Raw Blame History

常见问题

安装相关

主题安装后页面空白？

检查以下几点：

  1. 确认 Halo 版本 >= 2.26.0
  2. 确认主题已启用
  3. 清除浏览器缓存后重试（Ctrl+Shift+R 强制刷新）
  4. 检查 Halo 后台日志是否有报错

主题设置保存后没有生效？

  1. 清除浏览器缓存（Ctrl+Shift+R 强制刷新）
  2. 如果使用 Docker 部署，尝试重启容器：docker restart halo
  3. 检查 Halo 缓存设置

Docker 部署后主题文件更新不生效？

手动更新主题文件后需要重启容器：

docker cp templates/ halo:/root/.halo2/themes/warm-island/
docker restart halo

升级主题后整站都没有样式？

主题的 CSS / JS 文件名带内容哈希，每次构建都会变化。如果 Halo 页面缓存或前置反向代理 （OpenResty、CDN 等）里还留着上一版本的 HTML，它请求的仍是已被删除的旧文件名， Halo 找不到文件时会返回 500（日志里能看到 FileNotFoundException: .../templates/assets/Layout.xxxx.css）， 于是样式全部失效。

依次处理：

  1. Halo 后台执行一次「清理缓存」（设置 → 缓存，或直接重启 Halo / 容器）
  2. 刷新 CDN、反向代理缓存
  3. 浏览器强制刷新（Ctrl+Shift+R）

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 分钟就会回源，无需手动刷新

长期建议：以后每次升级主题或修改主题设置后，都点一次「刷新页面缓存」， 否则未登录访客最长会一直看到旧页面（插件不会自动感知主题层的变更）。

功能相关

鼠标点击效果 / 拖尾效果开启了却没反应？

  1. 确认「总体样式 → 鼠标点击效果」开关已开启并点击了保存
  2. 确认「点击效果类型」没有选择「关闭」（选了关闭时即使开启开关也不会有任何特效）
  3. 清除浏览器缓存后重试；老版本的浏览器请更新到较新的 Chrome / Edge / Firefox / Safari

若仍无效，打开浏览器控制台（F12）检查是否有 JS 报错 —— 第三方脚本报错会中断后续脚本执行。

搜索按钮不显示？

搜索功能依赖 Halo 搜索插件：

  1. 确认已安装 搜索插件
  2. 确认主题设置中「显示搜索按钮」已开启
  3. 确认插件已启用
  4. 支持快捷键 Ctrl+K（macOS 为 ⌘K）唤起搜索

瞬间/图库/友链页面显示插件未安装？

这些页面需要安装对应的 Halo 插件：

页面 所需插件
瞬间 PluginMoments
图库 PluginPhotos
友链 PluginLinks
朋友圈 PluginFriends

安装并启用插件后，页面会自动显示内容。未安装插件时页面会显示友好的提示信息。

一言 API 加载失败？

  1. 检查网络是否能访问 https://v1.hitokoto.cn/
  2. 如果在国内服务器，可能存在网络延迟
  3. 可以在主题设置中更换一言 API 地址为自建镜像

文章目录不显示？

  1. 确认文章内容中包含标题（h2-h6）
  2. 确认主题设置中「显示文章目录」已开启
  3. 桌面端需要屏幕宽度 >= 1280px 才会显示侧边目录
  4. 移动端通过右下角悬浮按钮打开目录抽屉

代码高亮不生效？

  1. 确认代码块使用了正确的语言标记（如 ```python）
  2. Prism.js 支持自动语言检测，但部分语言需要手动标记
  3. 检查浏览器控制台是否有 Prism.js 加载错误

样式相关

如何更换强调色？

在主题设置 → 样式设置 → 强调色 中选择或输入颜色值。也可以通过自定义 CSS 覆盖 --accent 变量，详见 自定义 CSS。

深色模式下某些元素颜色不对？

  1. 尝试清除浏览器缓存
  2. 检查是否有自定义 CSS 只设置了浅色模式的值
  3. 确保深色模式的变量覆盖在 html.dark 选择器下

自定义 CSS 不生效？

  1. 检查 CSS 语法是否正确
  2. 确认选择器特异性足够覆盖默认样式
  3. 使用浏览器开发者工具检查元素的实际样式
  4. 尝试添加 !important 提高优先级

其他

浏览器控制台出现 Tracking Prevention 警告？

这是浏览器的追踪防护功能拦截了第三方脚本（如 Microsoft Clarity），不是主题代码问题，不影响网站功能。

icon-192x192.png 404 错误？

这是 Halo 系统 PWA manifest 配置问题，需要在 Halo 后台设置 PWA 图标，与主题无关。

如何报告 Bug？

请在 GitHub Issues 中提交，包含以下信息：

  • Halo 版本
  • 主题版本
  • 问题描述和复现步骤
  • 浏览器和设备信息
  • 相关截图
Reference in New Issue View Git Blame Copy Permalink