MatrixLight Docs

Appearance

故障排除 ​

本文档提供了 EsbpmPlugin 的常见问题及解决方案，帮助您快速识别和解决使用过程中可能遇到的问题。

插件启动问题 ​

插件未加载 ​

  • 问题：启动服务器后，插件未显示为已加载
  • 解决方法：
    1. 检查插件是否正确放置在 plugins 文件夹中
    2. 确认插件文件名以 .jar 结尾
    3. 查看服务器日志文件（logs/latest.log）中是否有与插件相关的错误信息
    4. 确保使用的是兼容的 Minecraft 版本（1.21）
    5. 检查插件是否与其他已安装的插件存在兼容性问题

配置文件未生成 ​

  • 问题：首次启动服务器后，config.yml 文件未在 plugins/EsbpmPlugin/ 目录中生成
  • 解决方法：
    1. 停止服务器
    2. 确认插件 JAR 文件完整且未损坏
    3. 手动创建 plugins/EsbpmPlugin/ 目录
    4. 重新启动服务器
    5. 如果问题仍然存在，尝试删除插件并重新下载

功能问题 ​

飞行功能不工作 ​

  • 问题：玩家无法使用 /fly 命令或飞行功能不正常
  • 解决方法：
    1. 确认玩家拥有 esbpm.command.fly 权限
    2. 检查 config.yml 中的 flight.allow-in-survival 设置是否为 true（如果需要在生存模式下飞行）
    3. 确认服务器设置中的 allow-flight 配置是否为 true
    4. 检查是否有其他插件可能与飞行功能冲突
    5. 尝试让玩家重新加入服务器

速度效果未应用 ​

  • 问题：玩家没有获得速度效果或效果强度不符合预期
  • 解决方法：
    1. 检查 config.yml 中的 speed-effect.enabled 设置是否为 true
    2. 确认 speed-effect.level 的值是否在 1-5 的范围内
    3. 检查玩家是否拥有 esbpm.speed.bypass 权限（如果应该绕过速度限制）
    4. 尝试让玩家重新加入服务器以重新应用效果
    5. 检查是否有其他插件可能影响速度效果

游戏模式强制功能不工作 ​

  • 问题：非管理员玩家没有被强制设置为指定的游戏模式
  • 解决方法：
    1. 检查 config.yml 中的 gamemode.enabled 设置是否为 true
    2. 确认 gamemode.forced-mode 的值是否为有效游戏模式（0-3）
    3. 检查玩家是否拥有 esbpm.gamemode.bypass 权限（如果不应该绕过强制游戏模式）
    4. 尝试让玩家重新加入服务器
    5. 检查服务器控制台是否有相关错误信息

危险物品限制不工作 ​

  • 问题：被限制的物品（如 TNT、末影珍珠）仍可被玩家使用
  • 解决方法：
    1. 检查玩家是否拥有 esbpm.bypass.banneditems 权限（如果不应该绕过限制）
    2. 确认相关物品是否在插件的限制列表中
    3. 检查是否有其他插件可能覆盖了此限制功能
    4. 查看服务器日志是否有相关错误信息

服务器性能问题 ​

插件导致服务器卡顿 ​

  • 问题：安装插件后，服务器出现卡顿或性能下降
  • 解决方法：
    1. 尝试禁用部分功能（如速度效果）来确定是否与特定功能相关
    2. 检查服务器资源使用情况（CPU、内存）
    3. 确认服务器有足够的资源运行所有已安装的插件
    4. 检查是否有插件冲突
    5. 考虑更新插件到最新版本

插件消耗过多内存 ​

  • 问题：插件占用了异常高的内存资源
  • 解决方法：
    1. 检查服务器上的玩家数量，大量玩家可能增加插件资源消耗
    2. 尝试减少活动功能的数量
    3. 确认插件版本是否与服务器版本完全兼容
    4. 考虑限制某些高资源消耗功能的使用

兼容性问题 ​

与其他插件冲突 ​

  • 问题：EsbpmPlugin 与其他已安装的插件存在冲突
  • 解决方法：
    1. 逐一禁用其他插件，找出与 EsbpmPlugin 冲突的插件
    2. 检查插件更新，看是否有修复冲突的版本
    3. 考虑调整插件加载顺序
    4. 在插件社区寻求帮助或报告冲突问题

与服务器版本不兼容 ​

  • 问题：插件无法在特定的 Minecraft 版本上正常工作
  • 解决方法：
    1. 确认插件版本与服务器版本兼容（当前支持 1.21）
    2. 检查是否有针对您服务器版本的插件更新
    3. 考虑升级或降级服务器版本以匹配插件要求

配置问题 ​

配置修改后不生效 ​

  • 问题：修改配置文件后，更改没有在游戏中生效
  • 解决方法：
    1. 确认正确保存了配置文件的更改
    2. 尝试重启服务器以完全加载新配置
    3. 使用 /esbpm reload 命令重新加载插件配置（需要 esbpm.reload 权限）
    4. 检查配置文件语法是否正确，YAML 格式错误可能导致配置被忽略
    5. 确认修改的是正确的配置文件（路径：plugins/EsbpmPlugin/config.yml）

配置文件被重置 ​

  • 问题：每次服务器重启后，配置文件被重置为默认值
  • 解决方法：
    1. 确认服务器对配置文件有写入权限
    2. 检查服务器是否在只读模式下运行
    3. 尝试修改配置文件权限设置
    4. 考虑在服务器完全启动后再修改配置文件

日志分析 ​

如何查看服务器日志 ​

服务器日志通常包含插件错误和警告信息，是排查问题的重要工具：

  1. 访问日志文件：

    • 日志文件位于服务器目录的 logs 文件夹中
    • latest.log 包含最近一次服务器运行的日志
    • 历史日志按日期存储在 .gz 压缩文件中

  2. 查找插件相关错误：

    • 在日志中搜索 "EsbpmPlugin" 或 "ESBPM" 来查找与插件相关的条目
    • 特别注意 ERROR 和 WARNING 级别的消息
    • 错误堆栈跟踪可以帮助识别具体问题

  3. 常见错误消息及含义：

    • Could not load plugin: EsbpmPlugin：插件无法加载，通常是兼容性问题或损坏的 JAR 文件
    • Permission denied: cannot create config.yml：没有权限创建配置文件
    • Invalid configuration: speed-effect.level must be between 1 and 5：配置值无效

获取支持 ​

如果您遇到本文档未涵盖的问题，可以通过以下方式获取支持：

  1. 检查文档：

  2. 社区支持：

    • 在 Minecraft 插件社区论坛寻求帮助
    • 查看插件的 GitHub 仓库是否有已知问题或解决方案

  3. 报告问题：

    • 如果您确定发现了插件的 Bug，请按照 CONTRIBUTING.md 中的指南提交 Bug 报告
    • 提交问题时，请包含服务器日志、配置文件和详细的问题描述

  4. 联系开发者：

    • 如果问题紧急或影响服务器运营，可以尝试直接联系插件开发者
    • 联系方式可在 README.md 中找到

Copyright © 2025-Shanghai MatrixLight Technology Co., Ltd. All rights reserved.