> For the complete documentation index, see [llms.txt](https://doc.stellarvan.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.stellarvan.cn/readme/tiao-shi-yu-fa-bu/tiao-shi-yu-pai-cuo.md).

# 调试与排错

## 调试与排错

写插件时，问题通常出在这几类地方：

* 插件根本没加载
* 命令或事件没有生效
* 版本不兼容
* 依赖缺失
* 数据没有保存

### 先看服务器启动日志

先确认插件有没有被加载。

如果加载失败，控制台通常会直接给出异常栈。 先读第一段报错，再往下看调用链。

### 最常见的排错清单

#### 插件没出现在 `/plugins`

先检查：

* jar 有没有放进 `plugins/`
* `plugin.yml` 是否存在
* `main` 类路径是否正确
* `api-version` 是否与目标版本匹配

#### 命令不能执行

先检查：

* 命令是否写进 `plugin.yml`
* `getCommand(...)` 是否为 `null`
* 执行器是否已注册
* 权限是否正确

#### 事件没有触发

先检查：

* 监听器是否已注册
* 方法是否加了 `@EventHandler`
* 事件类型是否写对

#### 一启动就报 `ClassNotFoundException`

这通常说明类路径或依赖有问题。

先确认你没有错误引用不存在的类。 如果用了第三方库，还要确认打包方式是否正确。

### 用日志定位问题

日志是最实用的调试方式。

{% code title="MyPlugin.java" %}

```java
getLogger().info("插件开始加载配置");
getLogger().info("已注册 heal 命令");
```

{% endcode %}

关键路径都可以打日志。 尤其是插件启用、命令执行和数据保存。

### 不要依赖 `/reload`

`/reload` 很方便，但不可靠。

它会留下旧任务、旧监听器和旧状态。 很多“偶发 bug”其实是它制造的。

开发时更推荐：

* 停服
* 替换 jar
* 重启测试服

### 养成这几个习惯

* 每次只改一小块逻辑
* 改完立刻测试
* 保留清晰的日志
* 在干净环境里复测

这样最容易定位问题。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.stellarvan.cn/readme/tiao-shi-yu-fa-bu/tiao-shi-yu-pai-cuo.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.