常见问题
安装与配置
Q: 插件安装后没有反应？
可能原因：
- Halo 版本低于 2.22.1
- Java 版本不是 JDK 21
- JAR 文件不完整或插件未正常启动
处理方式：检查 Halo 和 JDK 版本，重新安装 JAR，并查看 Halo 日志。
Q: 配置验证失败怎么办？
检查以下项目：
- Steam API Key 是否正确
- Steam ID 是否为 17 位 SteamID64
- Steam 隐私设置中「我的个人资料」和「游戏详情」是否公开
- 服务器是否能访问 Steam API，国内服务器建议配置代理
Q: 修改配置后为什么没有立即生效？
页面列表数据由后台预热缓存提供，已缓存的数据不会因为配置保存立即重拉。
- API Key、Steam ID、代理、语言、是否包含免费游戏、隐藏游戏等变更：点击「刷新缓存」或等待下一轮后台预热
- 游戏卡片详情：按「缓存过期时间」过期后重新拉取
数据显示
Q: 页面显示「部分 Steam 数据加载失败」？
通常是 Steam API 访问失败、配置错误或隐私设置不公开。
处理方式：
- 确认 Steam API Key 和 Steam ID 正确
- 确认 Steam「我的个人资料」和「游戏详情」公开
- 点击「验证配置」
- 国内服务器配置 Steam API 代理
- 适当增大 API 请求超时时间
Q: 游戏库中缺少某些游戏？
可能原因：
- 「包含免费游戏」关闭，免费游戏未进入游戏库
- 游戏被加入「隐藏的游戏」
- Steam 隐私设置不是公开
- 缓存还没有刷新
处理方式：检查配置后点击「刷新缓存」或等待下一轮库藏信息预热。
Q: 游戏封面为空或显示占位图？
封面来自 GetItems 返回的真实 store_item_assets 地址，可能为空的情况包括：
- GetItems 没有返回封面资源
- 首次拉取失败且没有旧封面可回退
- 商店明确不可见（
visible=false），页面会显示「不可用」徽章并使用占位图
headerImageUrl=null 不一定代表下架。只有 delisted=true 才表示 GetItems 明确返回商店不可见。
Q: 为什么显示「不可用」徽章？
当 GetItems 对该游戏返回 visible=false 时，插件会设置 delisted=true，页面显示「不可用」。这表示当前地区或状态下商店不可见，可能是地区锁、已下架、审核限制等，Steam 接口无法细分。
GetItems 没返回某个 AppID 不会被当作不可用。
Q: 最近游玩没有库外标识？
inLibrary 需要当前游戏库缓存作为对照。冷启动、刚刷新缓存或游戏库预热失败时，最近游玩可能暂时不显示库外标识。等待库藏信息预热完成即可。
成就
Q: 最近游玩没有显示成就进度？
可能原因：
- 未开启「显示最近游玩成就进度」
- 最近游玩缓存尚未刷新
- 游戏没有成就系统
- Steam 隐私设置导致成就不可用
开启该选项后，成就会在最近游玩缓存刷新时补全，不是在每次页面访问时实时请求。
Q: 成就进度显示锁定？
通常是 Steam 隐私设置导致成就数据不可用。请将 Steam「游戏详情」设为公开，然后刷新缓存。
性能
Q: 页面加载很慢？
正常情况下页面只读缓存，应当很快。若仍慢，常见原因是：
- 插件刚启动或刚刷新缓存，后台还没完成首次预热
- 图片资源加载慢，需要配置「游戏图片加速域名」
- 后台一直无法访问 Steam API，缓存始终为空
「显示最近游玩成就进度」会增加后台预热耗时和 Steam API 调用量，但缓存命中后的页面访问不会逐个游戏重新请求成就 API。
Q: Steam API 请求超时？
处理方式：
- 配置 HTTP 代理或自定义 API 地址
- 适当增加 API 请求超时时间
- 增大活跃信息/库藏信息刷新间隔，降低调用频率
热力图
Q: 热力图没有数据？
热力图只能记录启用后的数据，Steam 不提供历史每日数据。
处理方式：
- 确认已开启「启用游戏时长追踪」
- 等待每小时第 59 分钟的定时追踪
- 或点击「手动追踪时长」测试
- 确认这段时间确实有游戏时长变化
Q: 手动追踪提示处理了 0 款游戏？
如果距离上次追踪太近、没有新的游戏时长变化，或首次发现游戏只有初始快照，都可能处理 0 条每日记录。这是正常情况。
缓存
Q: 如何刷新缓存？
进入插件设置的「基本配置」，点击「刷新缓存」。刷新会清空内存缓存，并后台触发一次数据预热。刚刷新后的短时间内页面可能暂无数据。
Q: 缓存过期时间为什么不影响页面列表？
页面列表使用后台预热和 stale 缓存兜底。即使列表缓存按 TTL 已过期，页面仍会读取旧数据，直到下一轮预热成功写入新数据。「缓存过期时间」主要用于游戏卡片详情等按需查询。
代理与图片
Q: 国内服务器无法访问 Steam API？
在「代理配置」中启用 Steam API 代理，可选择 HTTP 代理或自定义 API 地址。修改后点击「刷新缓存」或等待下一轮后台预热。
Q: 图片加载慢？
填写「游戏图片加速域名」。插件只替换 URL 的域名部分，路径保持 Steam 原始路径，例如 store_item_assets/ 和 steamcommunity/。你的 CDN/反代需要按这些路径正确回源。
主题集成
Q: Finder API 返回 null？
Finder API 在请求失败或超时时返回 null，主题模板应做判空。缓存为空时也可能拿不到数据，例如刚启动、刚刷新缓存或后台持续失败。
Q: REST /games 或 /recent 未配置时返回什么？
公开 REST API 会返回 200 加空分页或空数组，避免出现 200 空 body。主题 Finder 仍遵循失败返回 null 的约定。
卸载
卸载插件会删除相关扩展数据，包括热力图记录。若可能重新使用，建议先禁用而不是卸载。