Files

T

nxxy335 125d0592c9 fix: 修复升级后整站无样式与点击特效失效

- 旧哈希静态资源随版本升级被删除，被缓存的 HTML 仍请求旧文件名导致
  FileNotFoundException 500，补 compat/assets 历史资源并在构建时合并
- postbuild 增加静态资源引用校验，缺失即构建失败
- ClickEffect 改为常驻配置节点 + data 属性驱动，避免配置未落库时静默失效；
  强制回流修正 transition 不触发；特效层挂到 body 下避免被导航栏遮挡
- 新增 scripts: postbuild/snapshot-assets/package/smoke-clickfx
- 版本 1.2.1

2026-09-27 16:27:51 +08:00

4.7 KiB

Raw Blame History

常见问题

安装相关

主题安装后页面空白？

检查以下几点：

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

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

清除浏览器缓存（Ctrl+Shift+R 强制刷新）
如果使用 Docker 部署，尝试重启容器：docker restart halo
检查 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），于是样式全部失效。

依次处理：

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

v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖），即使缓存里的旧 HTML 被再次请求也不会 500，但最终仍建议清一次缓存以使用最新样式。

功能相关

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

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

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

搜索按钮不显示？

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

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

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

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

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

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

一言 API 加载失败？

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

文章目录不显示？

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

代码高亮不生效？

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

样式相关

如何更换强调色？

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

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

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

自定义 CSS 不生效？

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

其他

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

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

icon-192x192.png 404 错误？

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

如何报告 Bug？

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

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

4.7 KiB Raw Blame History Unescape Escape