常见问题与排错
适用版本 ≥ 2.0.0 ｜ 后台路径：无
按「现象 → 原因 → 处理」组织。排查前先做两件事：强刷页面（排除缓存）、切换到默认主题对比（判断是主题还是插件问题）。
安装与升级
启用后样式全乱 / 像没加载 CSS
多为浏览器或 CDN 缓存。强刷（Cmd + Shift + R / Ctrl + F5），CDN 场景刷新缓存目录。
提示 Halo 版本不兼容 主题要求 Halo ≥ 2.25.0。先在后台「系统 → 关于」确认版本并升级。
升级后部分设置变回默认 2.x 调整了设置分组，被移动的分组不会自动迁移，需要按新的分组名重新设置。
上传主题包失败
多为反向代理上传限制，调大 Nginx client_max_body_size；同时确认 zip 根目录包含 theme.yaml。
显示与布局
Banner 不显示 检查「布局设置 → Banner 布局 → 模式」是否为「关闭/纯色模式」；确认 Banner 样式里已上传图片或视频；移动端若开启「移动端独立来源」但没填图源，会回落到电脑端，若电脑端也为空则不显示。
全屏透明模式下卡片不透明 / 不磨砂 需要同时开启「样式设置 → 样式开关 → 高级材质」，并用「壁纸透明度」「卡片透明度」调节强度。
分类导航栏 / 瞬间预览条不出现 两者默认关闭，分别在「页面布局 → 分类导航栏」「页面布局 → 瞬间预览条」开启。瞬间预览条还需要安装并启用瞬间插件，且移动端不显示。
侧边栏小组件没有吸顶 吸顶受「前缀规则」限制：未勾选吸顶的小组件必须排在列表最前面。只要它前面有已勾选吸顶的条目，后面的未勾选条目就可能表现出吸顶。详见 小组件与布局。
两栏布局看不到目录 两栏使用悬浮目录，不占侧栏；三栏才把目录挂进侧栏。目录是否出现还取决于「文章 → 目录 → 启用目录」。
文章页目录为空
文章正文没有 h2 / h3 标题时目录为空；也可能被「目录最大深度」截断。
移动端菜单打不开 / 样式怪 确认「菜单栏设置 → 移动端菜单样式」是手风琴还是抽屉；切换后强刷，避免旧 JS 缓存。
功能与交互
看不到访客样式面板（显示设置按钮） 需要「菜单栏设置 → 访客样式切换 → 允许访客切换样式」开启；三个标签页还要各自开启，全部关闭时按钮不显示。
访客切换的样式不生效 访客设置保存在浏览器本地，会覆盖后台默认值；清除站点数据或点击面板里的重置可恢复默认。
分享海报生成为空白 海报由前端绘制，图片跨域会污染画布导致失败。检查封面 / 头像是否为同域地址或已配置 CORS。
点赞数不增加 点赞依赖后端接口，先确认已登录状态下的接口返回；主题侧只负责展示与提交。
天气 / 欢迎弹窗总显示默认城市 两者共用「侧边栏 → 天气小组件 → 腾讯位置服务 Key」。Key 未配置、配额用尽或被域名白名单拦截时会走回退城市或降级文案。
一言一直显示兜底文案 上游 API 超时（默认 5 秒）会显示兜底文案；可换自定义 API 地址。
性能与图片
开启图片处理后封面依旧很大 非 Halo 内部存储时，需要先在对应服务端（ESA / OSS / EdgeOne / COS / 七牛 / 又拍云）开启图片处理；自定义模式需要填对参数格式。
首页加载慢 依次排查：Banner 是否为超大视频、是否开启预加载过多数量的轮播图、卡片封面宽度是否设为 0（不压缩）、是否开启了樱花等持续动画。
深色模式切换动画异常（Mac） 「配色切换动画」中的「圆形扩散 / 擦除」在部分 Mac 浏览器上表现异常，建议改用淡入淡出。
插件相关
友链 / 朋友圈页面空白 两页都依赖链接管理插件。友链页还需要插件提供的数据；朋友圈页面需在「扩展页面 → 朋友圈页面」配置拉取数量。
瞬间 / 图库 / 项目集页面 404 对应插件未启用。主题只提供模板，路由由插件注册。
关于页的「我的项目」「订阅更新」不显示 分别依赖项目集插件与文章订阅插件；未安装时对应卡片自动隐藏。
评论区不显示 需要评论插件；同时确认页面 / 文章本身允许评论。
如何反馈
提 Issue 时请附上：
- Halo 版本、Ethereal 版本、浏览器与版本
- 复现步骤（从哪个页面、点了什么）
- 截图或录屏，涉及布局问题请注明屏幕宽度
- Halo 日志中相关的报错片段
Issue 地址：https://github.com/AloneNanNan/halo-theme-ethereal/issues