Skip to content

FAQ Troubleshooting

Jump to bottom
SSOrangeCATY edited this page Sep 16, 2026 · 3 revisions

故障排查

本页面收集 BlockOffensive 常见问题和排查方向。

启动失败

检查 Minecraft 与 Forge 版本

当前源码基线面向：

  • Minecraft 1.20.1
  • Forge 47.4.10
  • Java 17（运行与源码目标）

如果日志中出现 loader、minecraft、forge 版本范围不匹配，请先确认版本。

检查必须依赖

共同依赖：

  • FPSMatch

mods.toml 中的 fpsmatch 要求版本 [1.3.0,) 且作用于两端。Modern UI [3.12.0.1,) 只在客户端强制；playerAnimator [1.0.2-rc1,) 和 bendy-lib [4.0.0,) 是客户端可选依赖。专用服务端无需安装这些客户端依赖。

检查可选兼容模组版本

如果安装了 TaCZ、Physics Mod、CounterStrikeGrenade、KubeJS、Hit Indication 等模组，请确认版本与 README 兼容矩阵一致。可选依赖版本不匹配可能导致兼容层行为异常。

/cs2 无法使用

常见原因：

现象 原因
提示只有玩家可执行 命令执行者不是玩家实体。
提示没有加入 CS 地图 玩家不在 CSGameMap 中。
action 没有效果 当前地图没有注册该 action，或 action 只适用于爆破模式。

排查步骤：

  1. 确认玩家已经加入 cs 爆破模式地图。
  2. 使用 /fpsm help 查看基础命令。
  3. 使用 /cs2 a、/cs2 da 等已知 action 测试。
  4. 如果是 debug action，确认玩家权限等级至少为 2。

无法打开商店

可能原因：

  • 玩家未加入地图。
  • 游戏未开始。
  • 当前地图不支持商店。
  • 购买时间已过。
  • 玩家离开了购买区域。

对应提示可在语言文件中看到：

  • key.blockoffensive.open.shop.failed.no_map
  • key.blockoffensive.open.shop.failed.game.not_started
  • key.blockoffensive.open.shop.failed.purchase_time.expired
  • key.blockoffensive.open.shop.failed.left.purchase_area
  • key.blockoffensive.open.shop.failed.game_type.no_shop

C4 无法放置

可能原因：

  • 玩家不在指定爆破区域。
  • 地图没有定义爆破区域。
  • 玩家没有加入爆破模式地图。
  • 游戏尚未开始。
  • 玩家未加入队伍或不满足阵营条件。

排查建议：

  1. 检查地图爆破区域是否配置。
  2. 确认玩家在 cs 地图中。
  3. 确认玩家属于可放置 C4 的阵营。
  4. 确认比赛已开始且处于正式回合。

拆弹没有进度

排查方向：

  • 确认 C4 已经放置。
  • 确认玩家正在看向 C4。
  • 确认按键绑定未冲突。
  • 确认玩家处于可拆弹阵营。
  • 查看客户端 HUD 或 Web API 中 dismantleBombProgress 是否变化。

HUD 或 TAB 不显示

排查方向：

  • 确认玩家进入了 cs 或 csdm 地图。
  • 确认 FPSMatch 客户端数据已同步。
  • 确认客户端配置未禁用相关 HUD。
  • 确认没有其他 UI/渲染模组冲突。
  • 如果修改过源码，确认 BOClientBootstrap 中 HUD/TAB 注册仍存在。

击杀消息或击杀图标不显示

检查客户端配置：

配置 默认值
kill message.hudEnabled true
kill icon.killIconEnabled true

同时确认：

  • 玩家处于比赛中。
  • 服务端正常发送 DeathMessageS2CPacket。
  • 客户端没有被其他 HUD Mod 覆盖。

Web API 无法访问

默认地址：

http://localhost:8080/api/data

必须满足：

  • webServerEnabled=true
  • 当前客户端在地图中
  • 当前客户端在比赛中
  • 当前客户端是旁观者
  • 端口未被其他程序占用

如果请求非 GET 方法，会返回 405。

如果端口被占用，可以修改 webServerPort。

从源码构建失败

Java 版本错误

源码目标和模组运行环境为 Java 17，但完整构建的 createMinecraftArtifacts 任务还需要 Java 21 toolchain。先检查 Gradle 实际发现的 JDK：

.\gradlew.bat javaToolchains --console=plain

如果只找到一个版本，请配置本机 JDK 或 Gradle toolchain 路径，让 Java 17 和 Java 21 都可用。

Gradle 依赖下载失败

项目使用多个 Maven 仓库，包括：

  • Maven Central
  • Curse Maven
  • Modrinth Maven
  • IzzelAliz Maven
  • Spigot snapshots
  • Sonatype
  • Latvian Maven
  • Architectury Maven

如果网络不稳定，重试：

.\gradlew.bat compileJava --console=plain

FPSMatch 本地子项目异常

BlockOffensive 使用 includeBuild("FPSMatch") 引入本地 FPSMatch。请确认：

  • FPSMatch/ 目录存在。
  • FPSMatch/build.gradle 可被 Gradle 读取。
  • 如果修改了 FPSMatch，也要一起修复编译错误。

开发客户端启动慢或卡住

建议：

  • 等待依赖下载完成。
  • 删除损坏的 Gradle 缓存后重试。
  • 确认 Gradle 同时能发现 Java 17 和 Java 21 toolchain。
  • 使用 --console=plain 获取更稳定日志。
.\gradlew.bat runClient --console=plain

Physics Mod 相关异常

BlockOffensive 包含 Physics Mod 兼容层和 ragdoll 移除同步包。如果相关行为异常：

  1. 确认 Physics Mod 版本与兼容矩阵一致。
  2. 临时移除 Physics Mod 验证问题是否消失。
  3. 检查是否有死亡代理或 ragdoll 相关报错。

反馈问题时建议提供

  • Minecraft 版本。
  • Forge 版本。
  • BlockOffensive 版本。
  • FPSMatch 版本。
  • 完整 Mod 列表。
  • 客户端或服务端 latest.log。
  • 复现步骤。
  • 地图类型：cs 或 csdm。
  • 是否使用 TaCZ、Physics Mod、KubeJS 等兼容模组。

Clone this wiki locally