halo-theme-WarmIsland/docs/faq.md

常见问题

安装相关

升级主题后首页 404「资源不存在 / Template index was not found」？

这是安装包里没有模板文件，不是主题代码或 Halo 版本问题。Halo 升级主题会用新包覆盖原主题目录， ZIP 里缺少 templates/index.html 时，渲染首页找不到 index 模板，直接返回 404。

如何确认：解压待上传的 ZIP，根目录应有 theme.yaml、settings.yaml 和 templates/ 目录， 其中有 index.html、post.html 等 20+ 个 .html。若只有几个 .yaml，就是「空壳包」—— templates/ 被 .gitignore 忽略，从源码仓库打包前没执行 pnpm build 就会这样。

处理：

1. 用完整安装包（Release 里的 ZIP）在 Halo 后台 → 主题管理 → 重新上传升级
2. 或本地执行 pnpm release（build → snapshot → package）重新生成 dist/warm-island-<version>.zip
3. 升级完成后清理一次 Halo 页面缓存 / CDN 缓存

当前版本的 pnpm package 会校验 templates/index.html、模板数量、资源目录与版本号一致性， 构建产物缺失或不完整时直接报错退出，不会再产出空壳包。

主题安装后页面空白？

检查以下几点：

1. 确认 Halo 版本 >= 2.27.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

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

主题会向第三方服务发请求吗？

默认不会。 所有脚本、样式、字体、图标、主题 Logo 与一言句子库都随主题自托管， 页面不预连接任何 CDN，也不加载远程脚本；Hero「描述文案来源」默认为「无」，欢迎弹窗默认关闭。 只有两类例外：

1. 访客主动点击分享按钮 / 备案链接 / 应用市场链接时才跳转到对应站点；
2. 站点管理员在主题设置里显式填写了「自定义一言 API」或「自定义 IP 定位 API」—— 后者会把访客 IP 发送给该第三方服务换取地理位置，需自行在站点隐私说明中披露， 详见 README「外部资源与隐私」。

可选接口地址（仅作候选，主题不会自动请求）：

能力	可选地址
一言	https://v1.hitokoto.cn/（选择「一言」时自动填入）
IP 定位主 / 备选 API	https://myip.ipip.net/json、https://r.inews.qq.com/api/ip2city?otype=json

完整逐项说明见 README 的「外部资源与隐私」章节。发版前可运行 pnpm audit:external 复核。

一言不显示，或想换成自己的句子？

1. Hero「描述文案来源」默认为「无」，此时不显示描述文案、不渲染一言元素，零外部请求； 想显示句子请改为「一言」
2. 选择「一言」后会自动填入 https://v1.hitokoto.cn/，此时才会产生外部请求； 把该字段清空即回退到主题内置的 assets/data/hitokoto.json 本地句子库（零外部请求）， 直接编辑该 JSON 即可替换文案。只有填写后才会向该地址发起请求，需自行在站点隐私说明中披露， 详见 README「外部资源与隐私」
3. 「自定义」模式显示「自定义描述文案」中的静态文本，不发起任何请求； 「句子类型」筛选仅对填写了 API 的一言模式生效

文章目录不显示？

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

代码高亮不生效？

主题不再自带 Prism.js 运行时（含 autoloader），因此不会自动给代码块加语法着色：

1. 安装 Halo 应用市场的代码高亮插件，或启用「API 扩展包」的服务端代码高亮
2. 主题设置 → 文章 → 「代码高亮主题」仅切换本地自托管的 Warm / Cold .token 配色
3. 确认代码块使用了正确的语言标记（如 ```python），以便插件识别语言

样式相关

如何更换强调色？

在主题设置 → 样式设置 → 强调色 中选择或输入颜色值。也可以通过自定义 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？

请在 源码仓库 Issues 中提交，包含以下信息：

• Halo 版本
• 主题版本
• 问题描述和复现步骤
• 浏览器和设备信息
• 相关截图