/debug 命令

来源：Commands/debug，英文修订 ID：3708743。

此命令仅适用于 Java 版，所需权限等级为 3。此条目描述时间分析器与函数追踪；性能分析器见 /perf，JVM 分析器见 /jfr。

启动或停止时间分析会话，取得函数执行的更详细信息。

语法

debug start：启动新的调试时间分析会话。
debug stop：停止当前调试时间分析会话。
debug function <name>：像 /function 一样运行函数，以取得命令执行的详细信息。不能被 /return run 或另一个 /debug function 直接或间接调用。

参数

<name>: function：函数资源位置，或带 # 前缀的函数标签；执行时解析为对应函数或函数标签。

结果与输出

命令不完整或任一参数指定错误时无法解析。已有分析会话时 start 失败；没有分析会话时 stop 失败；函数或函数标签不存在，或 function 由 /return run／另一个 /debug function 触发时失败。其他情况成功。

这些命令没有可取得的成功次数。失败时 success 与 result 为 0。成功时 success 为 1：start 的 result 为 0，stop 为分析期间平均 TPS（每秒游戏刻），function 为函数中的命令总数。

文件结构

函数追踪

使用 /debug function 时，在 .minecraft/debug 中创建 debug-trace-yyyy-MM-dd_HH.mm.ss.txt。文件中的标记含义如下：

标记	含义
`[C] <command>`	执行了命令
`[M] <message>`	返回一条消息
`[E] <message>`	返回失败消息
`[R = <num>] <command>`	命令返回了 Brigadier 返回值
`[C] <command> -> <num>`	执行命令并返回 Brigadier 返回值
`[F] <function> size=<num>`	调用了一个函数

大多数命令的 Brigadier 返回值等于可用 /execute store result 存储的 result。但对于包含以下一个或多个子命令的 /execute，每个分支会把其 success 值作为 Brigadier 返回值：

不在末尾的 ... if ...、... unless ...。
... as <targets> ...。
... at <targets> ...。
... positioned as <targets> ...。
... rotated as <targets> ...。
... facing entity <targets> <anchor> ...。

/return、/function 等部分命令没有 Brigadier 返回值。

分析结果（过时内容）

使用 /debug stop 时，会在 .minecraft/debug 中创建 profile-results-yyyy-MM-dd_HH.mm.ss.txt，包含分析转储结果。

报告（过时内容）

使用旧 /debug report 时，在 .minecraft/debug/profiling 创建 ZIP 文件。结构如下：

debug-report-yyyy-MM-dd_HH.mm.ss.zip
├── levels
│   └── minecraft 或其他自定义命名空间
│       └── overworld、the_end、the_nether 或自定义维度
│           ├── block_entities.csv
│           ├── chunks.csv
│           ├── entities.csv
│           ├── example_crash.txt
│           └── stats.txt
├── classpath.txt
├── example_crash.txt
├── gamerules.txt
├── stats.txt
└── threads.txt

block_entities.csv：世界中方块实体列表，格式为 x,y,z,type。
chunks.csv：区块信息，格式为 x,z,level,in_memory,status,full_status,accessible_ready,ticking_ready,entity_ticking_ready,ticket,spawning,entity_count,block_entity_count。
entities.csv：世界实体列表，格式为 x,y,z,uuid,type,alive,custom_name。
example_crash.txt：示例崩溃文件。
stats.txt：统计信息。
classpath.txt：Minecraft 使用的外部 JAR 的文件路径。
gamerules.txt：以 <gamerule>=<value> 格式列出游戏规则与值的纯文本文件。
threads.txt：所有正在运行的线程。

本文为 Minecraft Wiki 对应英文条目的中文翻译与改编，已按要求省略变更历史。原作者与贡献者见来源页及其历史；除另有说明外，按 CC BY-NC-SA 3.0 非商业、署名、相同方式共享。