nxxy335
5c7c6325b1
- 文档对齐 1.2.7：feed/RSS 聚合改由官方链接管理插件订阅承担、Halo 要求统一 >=2.27.0、补齐设置分组文档、清理与代码不符的描述，并修复正文引用块留白 - 三个可选 API 设置项 help 只保留功能说明，隐私披露统一由 README「外部资源与隐私」与文档站承载；字段恢复按开关条件显示，修正配置块缩进 - audit:external 改为防回潮检查：字段存在、help 不得出现披露文案、README 必须保留隐私披露章节
221 lines
11 KiB
Markdown
221 lines
11 KiB
Markdown
# 常见问题
|
||
|
||
## 安装相关
|
||
|
||
### 升级主题后首页 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. 确认已安装 [搜索插件](https://www.halo.run/store/apps/app-DlacW)
|
||
2. 确认主题设置中「显示搜索按钮」已开启
|
||
3. 确认插件已启用
|
||
4. 支持快捷键 `Ctrl+K`（macOS 为 `⌘K`）唤起搜索
|
||
|
||
### 瞬间/图库/友链页面显示插件未安装？
|
||
|
||
这些页面需要安装对应的 Halo 插件：
|
||
|
||
| 页面 | 所需插件 |
|
||
|------|----------|
|
||
| 瞬间 | [PluginMoments](https://www.halo.run/store/apps/app-SnwWD) |
|
||
| 图库 | [PluginPhotos](https://www.halo.run/store/apps/app-BmQJW) |
|
||
| 友链 | [PluginLinks](https://www.halo.run/store/apps/app-hfbQg) |
|
||
| 订阅动态 | 同为 [PluginLinks](https://www.halo.run/store/apps/app-hfbQg) 的 RSS 订阅能力，需选择「订阅」自定义模板 |
|
||
|
||
安装并启用插件后，页面会自动显示内容。未安装插件时页面会显示友好的提示信息。
|
||
|
||
**「朋友圈」插件已不再提供**：feed / RSS 聚合已由官方「链接管理」插件的订阅取代，
|
||
主题保留 `friends.html` 模板与「朋友圈」设置分组仅用于兼容旧站点。新站点请新建页面并选择
|
||
「订阅」自定义模板，详见 README「自定义页面模板」与[订阅页面](https://nxxy335.top/WarmIsland/pages/subscriptions.html)。
|
||
|
||
### 原来的「朋友圈」页面不能用了，怎么迁移？
|
||
|
||
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 定位主 / 备选 API | `https://myip.ipip.net/json`、`https://r.inews.qq.com/api/ip2city?otype=json` |
|
||
|
||
完整逐项说明见 README 的「外部资源与隐私」章节。发版前可运行 `pnpm audit:external` 复核。
|
||
|
||
### 一言不显示，或想换成自己的句子？
|
||
|
||
1. Hero「描述文案来源」**默认为「无」**，此时不显示描述文案、不渲染一言元素，零外部请求；
|
||
想显示句子请改为「一言」
|
||
2. 「自定义一言 API」字段在「描述文案来源」非「无」时显示，且默认预填 `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](/customize/custom-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](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland/issues) 中提交，包含以下信息：
|
||
|
||
- Halo 版本
|
||
- 主题版本
|
||
- 问题描述和复现步骤
|
||
- 浏览器和设备信息
|
||
- 相关截图
|