WarmIsland 暖屿

主题

常见问题 ​

安装相关 ​

升级主题后首页 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 部署后主题文件更新不生效？ ​

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

bash
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
订阅动态同为 PluginLinks 的 RSS 订阅能力，需选择「订阅」自定义模板

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

「朋友圈」插件已不再提供：feed / RSS 聚合已由官方「链接管理」插件的订阅取代， 主题保留 friends.html 模板与「朋友圈」设置分组仅用于兼容旧站点。新站点请新建页面并选择 「订阅」自定义模板，详见 README「自定义页面模板」与订阅页面。

原来的「朋友圈」页面不能用了，怎么迁移？ ​

  1. 安装 / 启用官方「链接管理」（PluginLinks）插件，把 RSS 订阅源迁到该插件的订阅中
  2. Halo 后台 → 页面 → 新建 → 自定义模板选择「订阅」（page_subscriptions.html）
  3. 在主题设置 → 订阅中调整每页条数、分页 / 下滑加载与列表 / 网格布局
  4. 确认动态正常展示后，删除旧的 /friends 页面与菜单项

旧的 friends.html 检测不到 plugin-friends 时只会显示空状态，不会影响站点其他页面。

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

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

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

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

能力可选地址
一言https://v1.hitokoto.cn/（选择「一言」时自动填入）
IP 定位主 / 备选 APIhttps://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 版本
  • 主题版本
  • 问题描述和复现步骤
  • 浏览器和设备信息
  • 相关截图

基于 GPL-3.0 许可发布

© 2026 暖心向阳335