主题
1. 为什么 HNWarehouse 启动不了？
先确认：
HNCore是否已安装并正常启动- 当前服务端是否为 Paper
1.20.1 - Java 版本是否为
17
当前 HNCore 是硬依赖，不是可选依赖。
2. 为什么仓库明明存在，但玩家打不开？
当前常见原因有：
- 仓库还没购买
- 仓库还没解锁
use-requirements当前不满足- 仓库处于锁定状态但
visible-when-locked为false
建议先执行：
text
/hnwarehouse inspect <玩家> access再看具体锁定原因。
3. 为什么奖励没有进到预期仓库？
优先检查：
capture.reward-enabled是否开启capture.reward-default-warehouse是否正确- 目标页面是否允许
reward来源 item-admission是否命中 blacklist 或未命中 whitelist
排查命令：
text
/hnwarehouse routecheck <玩家> <仓库> reward4. 为什么自动收纳没生效？
当前要同时满足：
- 全局
capture.auto-collect-enabled: true - 目标页面
auto-collect: true - 目标页面
allowed-sources包含auto-collect
另外要注意：当前自动收纳更多还是“路由骨架”，并不是所有监听与接管都已完整落地。
5. 为什么 routecheck 显示有拦截仓库？
这通常不是坏事，而是说明当前调试信息是完整的。
被拦截的常见原因包括：
- 访问条件不满足
- 仓库未解锁
item-admission命中 blacklist- 物品没有命中 whitelist
- 当前来源不允许进入对应页
routecheck 的意义就是把这些原因提前展示出来。
6. 为什么 withdraw 提取失败？
优先检查：
- 玩家是否在线
- 仓库 ID / 页面 ID / 条目 ID 是否正确
- 目标玩家背包是否能回填
- 当前仓库是否仍处于可访问状态
排查建议：
text
/hnwarehouse inspect <玩家> detail先确认条目确实存在，再执行 withdraw。
7. 为什么我改了仓库文件，但效果不对？
先确认两件事：
- 你改的是
plugins/HNWarehouse/warehouses/*.yml，而不是仓库源码模板 - 改完后是否执行了：
text
/hnwarehouse reload如果只是改了源码里的 src/main/resources/...，但线上目录里的实际配置没变，运行时当然不会生效。
8. 为什么配置了 placeholder / economy 条件，但一直失败？
分别确认：
placeholder条件：PlaceholderAPI是否已安装economy条件：HNEconomy是否已安装并可用
再用：
text
/hnwarehouse status看 Hook 状态是否正常。
9. 为什么 data/players 里没有新的玩家 YAML 文件？
这是正常现象。
当前 HNWarehouse 的主存储后端已经是数据库，旧：
text
plugins/HNWarehouse/data/players/主要用于历史版本升级时的 YAML 迁移来源。
也就是说：
- 新版本不再把它当成正式玩家主档目录
- 日常排查应优先看数据库状态、
status与inspect - 如果你是从旧版本升级，原始 YAML 可能仍然保留，但它不代表当前正式运行时主数据源
10. 为什么短时间连续 inspect 离线玩家时结果看起来一致？
当前离线摘要查询有短 TTL 缓存。
这意味着：
- 短时间内重复查看同一个离线玩家摘要，可能会复用缓存结果
- 写入发生后会主动失效缓存
- 这主要是为了减少短时间重复离线查询对数据库的压力
如果你怀疑结果没更新，先确认：
- 当前目标是不是离线玩家
- 是否刚好还处于摘要缓存时间窗内
- 是否已经发生写入并触发缓存失效
11. 玩家退出时会不会卡一下？
当前 join / quit / autosave 相关的 Session 生命周期已经按异步保存 / 异步卸载语义处理。
这意味着：
- 玩家退出时不再应该被简单理解成“主线程上同步整档落盘”
- 插件关闭仍然会走安全保存流程
- 管理员执行
reload时，重载本身已经切到后台执行，但仍会保留安全收尾语义 - 如果你看到偶发写入压力，更应优先排查数据库负载，而不是默认归因到“退出就同步卡顿”
12. 可以直接手改玩家 YAML 吗？
可以读，但不建议作为常规操作。
更推荐：
- 先用
status / inspect / routecheck排查 - 再用
unlockforce / unlockreset / withdraw做修复 - 最后才考虑人工核对数据库或旧 YAML 迁移源
因为当前正式状态不仅包含条目，还包含：
- 购买状态
- 解锁状态
- 页扩容状态
- 运行时 Session 状态
- 数据库中的分层持久化结构
旧 YAML 现在更适合作为历史迁移参考，而不是当前主运维入口。
13. 当前版本是否已经完整接管玩家物品流？
还没有。
当前已经具备：
- 仓库领域模型
- 统一投递路由
- 提取与查询能力
- 基础 GUI 与命令能力
但以下能力仍未完整接入：
- 掉落拾取接管监听器
- 死亡掉落改写
- 原版背包热栏投影
- 更完整的
InventoryClick/InventoryDrag接管策略
所以更准确的理解是：
当前 HNWarehouse 已经是可用的仓库系统骨架，但还不是“已完全接管所有物品流转”的最终态。