> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 常见问题
本页面解答 ArcPass 使用过程中的常见问题。
安装问题
插件无法加载
**症状**：服务器启动后看不到 ArcPass 相关日志
**解决方案**：
1. 确认 JAR 文件放在 `plugins` 文件夹中
2. 检查 Java 版本是否为 17 或更高
3. 查看服务器日志是否有错误信息
4. 确认使用的是 Paper/Spigot 1.18+ 或 Folia 1.19+
配置文件未生成
**症状**：`plugins/ArcPass` 文件夹为空或不存在
**解决方案**：
1. 检查文件夹写入权限
2. 查看控制台是否有权限错误
3. 手动创建 `plugins/ArcPass` 文件夹后重启
与其他插件冲突
**症状**：安装 ArcPass 后其他插件报错
**解决方案**：
1. 检查是否有重复的依赖库
2. 尝试更新冲突的插件
3. 查看错误日志确定具体冲突点
4. 在 Discord 社区反馈问题
许可证问题
许可证验证失败
**症状**：控制台显示 `License validation failed`
**可能原因和解决方案**：
1. **密钥错误**
* 检查 `license.yml` 中的密钥是否正确
* 注意大小写和特殊字符
2. **网络问题**
* 确认服务器可以访问 `license.kitemc.com`
* 检查防火墙设置
3. **绑定数量已满**
* 登录用户中心解绑不用的服务器
* 或升级到更高版本许可证
4. **许可证过期**
* 检查许可证有效期
* 续费或购买新许可证
更换服务器后无法使用
**症状**：迁移服务器后许可证无效
**解决方案**：
1. 登录 [KiteMC 许可证中心](https://license.kitemc.com/login)
2. 找到您的许可证
3. 解绑原服务器
4. 在新服务器上重新激活
许可证绑定失败
**症状**：`LIMIT_EXCEEDED` 或 `BINDING_FAILED`
**解决方案**：
1. 检查当前绑定数量是否已满
2. 解绑不使用的服务器
3. 确认服务器 IP 和端口正确
功能问题
经验不增加
**可能原因**：
1. 没有活动的赛季
2. 任务未正确配置
3. 玩家没有相应权限
**解决方案**：
1. 使用 `/arcpass admin season start` 开启赛季
2. 检查任务配置文件是否有语法错误
3. 确认玩家有 `arcpass.use` 权限
奖励无法领取
**可能原因**：
1. 等级不足
2. 未拥有对应档位
3. 已经领取过
**检查方法**：
```
/arcpass admin lookup <玩家名>
```
GUI 打不开
**可能原因**：
1. 插件未完全初始化
2. 许可证未激活
3. GUI 配置文件错误
**解决方案**：
1. 等待插件完全加载后再尝试
2. 检查许可证状态
3. 检查 `gui/*.yml` 文件是否有语法错误
任务进度不更新
**可能原因**：
1. 任务类型配置错误
2. 目标参数不匹配
3. 任务条件未满足
**排查步骤**：
1. 确认任务类型拼写正确
2. 检查目标参数（如方块/生物名称）
3. 开启调试模式查看详细日志
```
/arcpass admin debug toggle
```
兼容性问题
Folia 服务端问题
**Q: ArcPass 支持 Folia 吗？**
A: 完全支持。ArcPass 会自动检测 Folia 并使用兼容的调度器。
**Q: 某些功能在 Folia 上不工作？**
A: 检查第三方插件是否支持 Folia：
* DeluxeTags 不支持 Folia，请使用 TAB 替代
* 部分经济插件可能不兼容
PlaceholderAPI 变量不显示
**可能原因**：
1. PlaceholderAPI 未安装
2. 扩展未注册成功
3. 变量名拼写错误
**解决方案**：
1. 安装 PlaceholderAPI 2.11.0+
2. 重启服务器
3. 使用 `/papi parse me %arcpass_level%` 测试
4. 检查变量名是否正确（区分大小写）
经济插件不工作
**症状**：购买档位或经济奖励失败
**解决方案**：
1. 确认 Vault 或 CMI 已安装
2. 确认有经济插件（如 EssentialsX）
3. 测试经济插件是否正常工作
```
/eco give <玩家> 100
```
MythicMobs/Jobs 任务不触发
**可能原因**：
1. 插件版本不兼容
2. ID 配置错误
3. 事件未正确触发
**解决方案**：
1. 更新到推荐版本
2. 检查 ID 是否区分大小写
3. 开启调试模式确认事件触发
性能问题
服务器卡顿
**可能原因**：
1. 数据库操作缓慢
2. 排行榜计算频繁
3. 同时在线玩家过多
**优化建议**：
1. 使用 MySQL 替代 SQLite
2. 增加缓存时间
3. 优化数据库连接池配置
```yaml theme={null}
# database.yml
mysql:
pool:
maximum-pool-size: 10
minimum-idle: 5
```
内存占用高
**解决方案**：
1. 检查玩家数据缓存配置
2. 减少不必要的任务类型
3. 定期清理旧数据
配置问题
YAML 语法错误
**症状**：配置文件加载失败
**常见错误**：
1. 缩进使用了 Tab 而不是空格
2. 特殊字符未转义
3. 冒号后缺少空格
**建议**：
* 使用支持 YAML 的编辑器（VSCode + YAML 插件）
* 使用在线 YAML 验证工具检查
中文乱码
**解决方案**：
1. 确保配置文件使用 UTF-8 编码保存
2. 在 Notepad++ 或 VSCode 中转换编码
3. 重新生成配置文件
获取帮助
如果以上方案无法解决您的问题：
1. **查看详细日志**
```
/arcpass admin debug toggle
```
2. **导出诊断信息**
```
/arcpass admin debug
```
3. **联系支持**
加入社区获取实时帮助
[starry\_cbz@outlook.com](mailto:starry_cbz@outlook.com)
查看许可证状态和工单
提交 Bug 报告
提交问题时请提供：
* 服务端类型和版本
* ArcPass 版本
* 错误日志截图
* 相关配置文件
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.