配置
MCDR 的配置文件是 config.yml。它位于，也应位于 MCDR 的工作目录中
在启动时，MCDR 将尝试加载配置文件，并将缺失的选项（如果有）添加到你的配置文件末尾。如果配置文件不存在，MCDR 则将生成默认配置文件并退出
配置文件使用 YAML 格式
当 MCDR 运行时，你可以使用 !!MCDR reload config 命令（或其缩写 !!MCDR r cfg）来重载配置文件
参见
热重载 命令章节中更多与热重载相关的命令
基础配置
MCDR 的基础配置
language
MCDR 用于输出信息的语言
选项类型：
str默认值：
en_us可用选项：
en_us，zh_cn，zh_tw
服务端配置
与那个 MCDR 启动并控制的服务端相关的配置
working_directory
服务端的工作目录。你应该将所有与服务端相关的文件放入此目录
选项类型：
str默认值：
server
start_command
启动服务端的控制台命令。它可以是一个字符串，或一个字符串列表
（shell 模式）如果值为一个字符串，则命令将被视为一个 shell 命令，在 shell 环境中执行。推荐使用，因为它易于使用
start_command: echo Hello world from MCDReforged
（exec 模式）如果值是一个字符串列表，则给定命令将被直接 exec 执行。该模式可让服务端进程直接被 MCDR 接管（MCDR - server），而非通过一个 shell 进程间接地接管（MCDR - shell - server）
start_command: - echo - Hello world from MCDReforged
start_command: ['echo', 'Hello world from MCDReforged']
在 v2.13.0 版本加入.
参见
类 subprocess.Popen 构造函数中的 args 参数
如果你想要启动一个 Minecraft 服务端，下面是一些有用的例子。这些例子都用了单个字符串作为该选项的值，这将意味着将使用 shell 模式来启动服务端
start_command: java -Xms1G -Xmx2G -jar minecraft_server.jar nogui
如果 working directory 中已存在启动脚本，你可以：
start_command: start.bat
start_command: ./start.sh
如果命令中存在一些 YAML 不喜欢的字符（如 "、\），你可以从以下解决方案中任选一个：
# use "" to wrap the command and escape " and \
start_command: "\"C:\\Program Files\\Java\\jdk-17.0.3.1\\bin\\java.exe\" -Xms1G -Xmx2G -jar minecraft_server.jar"
# use '' to wrap the command
start_command: '"C:\Program Files\Java\jdk-17.0.3.1\bin\java.exe" -Xms1G -Xmx2G -jar minecraft_server.jar'
# use multi-line string
start_command: |-
"C:\Program Files\Java\jdk-17.0.3.1\bin\java.exe" -Xms1G -Xmx2G -jar minecraft_server.jar
# use "" to wrap the command and escape " and \
start_command: "\"/path/to my/java\" -Xms1G -Xmx2G -jar minecraft_server.jar"
# use '' to wrap the command
start_command: '"/path/to my/java" -Xms1G -Xmx2G -jar minecraft_server.jar'
# use multi-line string
start_command: |-
"/path/to my/java" -Xms1G -Xmx2G -jar minecraft_server.jar
备注
对于 Minecraft 服务端，你可能希望在 -jar 参数前面加一个诸如 -Dfile.encoding=UTF-8 的 JVM 属性，以确保服务端运行在一个 UTF-8 的环境中
见 encoding, decoding 小节以了解更多 Minecraft 服务端中与 UTF-8 编码相关的信息
选项类型：
str或List[str]默认值：
echo Hello world from MCDReforged
handler
不同服务端有着截然不同的输出和命令。服务端处理器是用于在各种服务端之间进行处理的模块，也是 MCDR 控制服务端的接入点
处理器确定解析服务端标准输出文本的特定方法，并使用正确的命令控制服务端
内置的处理器及其适用的服务端如下表所示：
处理器 |
兼容的服务端类型 |
|---|---|
vanilla_handler |
用于 原版 / Carpet / Fabric 服务端。只要服务端足够原版就行 |
beta18_handler |
用于低版本的原版服务端，如 MC < 1.7 的低版本，甚至到 beta1.8 版本。只在 1.6.4 和 beta 1.8.1 版本中进行了测试 |
bukkit_handler |
用于 1.14 版本以下的 Bukkit / Spigot 服务端，以及所有版本的 Paper / Mohistmc 服务端 |
bukkit14_handler |
用于 1.14 或以上版本的 Bukkit / Spigot 服务端 |
forge_handler |
用于 Forge 服务端 |
cat_server_handler |
适用于 CatServer 服务端 |
arclight_handler |
适用于 Arclight 服务端 |
bungeecord_handler |
用于 BungeeCord 服务端。请在启动命令的 |
waterfall_handler |
用于 WaterFall 服务端 |
velocity_handler |
用于 Velocity 服务端 |
basic_handler |
不进行任何分析并返回原始文本的处理器。除非你想使用 MCDR 启动非 Minecraft 相关的服务端，否则无需使用 |
选项类型：
str默认值：
vanilla_handler
encoding, decoding
用于编码消息至服务端标准输入 / 从服务端标准输出解码消息时，所用的编码 / 解码格式
留空以让 MCDR 使用系统编码。如果它不起作用（例如控制台中出现了乱码），你需要根据服务端的编解码方式手动配置这两个选项
对于原版 Minecraft 服务端，如果你的操作系统默认的字符集并非 UTF-8，强烈建议确保所有的编码 / 解码都使用 UTF-8 字符集，原因如下：
Python 3 使用 UTF-8 存储字符串
原版 Minecraft 服务端始终使用 UTF-8 读取 stdin
原版 Minecraft 服务端使用操作系统的默认字符集写入 stdout / stderr / 日志文件
你的操作系统使用的字符集可能不是 UTF-8，比如中文 Windows 可能使用 GBK 作为默认字符集
非 UTF-8 字符集在编解码过程中可能会引起烦人的编解码问题，导致 MCDR 无法与服务端正常通信
sequenceDiagram
participant MCDR
participant pipe
participant Minecraft
MCDR->>pipe: send "hello" (encoding)
pipe->>Minecraft: stdin (UTF-8)
Minecraft-->>pipe: stdout/stderr (OS charset)
pipe-->>MCDR: receive "world" (decoding)
为了让与服务端相关的一切编解码都用上 UTF-8，你可以参照如下方法：
让 MCDR 使用 UTF-8 与 Minecraft 服务端通信，即在 MCDR 配置中将
encoding和decoding设置为 utf8encoding: utf8 decoding: utf8
确保启动 Minecraft 的 JVM 也使用 UTF-8 作为默认字符集。你可以通过以下任一操作来实现：
-Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8
如果你在使用 Java 的长期支持（LTS）版本，如 8/11/17/21，那么你总是可以将此作为一个万能的 Java UTF-8 解决方案。未被识别的系统属性
stdout.encoding和stderr.encoding是无害的另见：下文“上述 JVM 参数的解释”小节
-Dfile.encoding=UTF-8 -Dsun.stdout.encoding=UTF-8 -Dsun.stderr.encoding=UTF-8
注意，
-Dsun.stdout.encoding和-Dsun.stderr.encoding是非标准的 API。另见：JEP 400-Dfile.encoding=UTF-8要使上面的那些 JVM 系统属性生效，你可以：
（推荐）修改服务端的启动命令。在
-jar参数之前添加下述参数start_command: java -Xms1G -Xmx2G -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -jar minecraft_server.jar # ^^^^^^^^^^^^^^^^^^^^^^^^^^^ insert these ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
如果你无法修改服务端的启动命令，你可以将上述参数插入环境变量
JAVA_TOOL_OPTIONSexport JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8"
然后，Minecraft 服务端在运行时就会使用 UTF-8 作为其标准 IO 流的字符集，此时 MCDR 将能完美地与服务端通信
当然，如果你确定你的操作系统使用的默认字符集是 UTF-8，那你什么都不需要做。你甚至可以将这两个 encoding/ decoding 选项留空来使用默认的系统字符集。
如果你的服务端有混合编码输出的情况，你可以提供一个字符串列表作为 decoding 选项的值，以提供所有可能的解码方式。此时，MCDR 将会逐一尝试所有提供的解码方法，直到解码成功
示例场景：Windows 中，shell 输出使用了系统编码（如 GBK），而服务端输出使用了 UTF-8
示例解决方案：
decoding: ['utf8', 'gbk']
encoding
选项类型：
Optional[str]默认值：
utf8例如：
utf8，gbk
decoding
选项类型：
Optional[str]或List[str]默认值：
utf8例如：
utf8，gbk,['utf8', 'gbk']
上述 JVM 参数的解释
对于 Minecraft 服务端，存在两种场景的输出内容到 stdout / stderr 的方法：
(a) 使用 log4j 打日志
原版 Minecraft 服务端使用 log4j 库进行日志记录。它的 log4j 配置中使用了
ConsoleAppender来将日志信息输出到 stdout，这最终会使用Charset.defaultCharset()来获取默认的编码字符集这种情况下使用UTF-8的解决方案：
-Dfile.encoding=UTF-8
(b) 直接使用 System.out 或 System.err 进行输出
有时 Minecraft 服务端可能会直接将信息打印到 stdout / stderr。在这种情况下，我们需要确保 System.out 和 System.err 都使用 UTF-8 字符集来编码输出
这种情况下使用UTF-8的解决方案：
Java 版本
用于确保使用了 UTF-8 的 JVM 参数
<= 1.17
-Dfile.encoding=UTF-81.18
-Dsun.stdout.encoding=UTF-8 -Dsun.stderr.encoding=UTF-8（非标准 API）>= 1.19
-Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8另见：
rcon
rcon 设置。若启用 rcon，则在 Minecraft rcon 服务端启动后，MCDR将自动连接到 rcon 服务端。这样插件就可以通过 rcon 向服务端发送命令
要配置 rcon 以便 MCDR 使用，请在 Minecraft 服务端的 server.properties 中找到以下几行：
enable-rcon=false
rcon.password=
rcon.port=25575
确保它们与 MCDR 配置相同
rcon.enable
rcon 开关
选项类型：
bool默认值：
false
rcon.address
用于 rcon 连接的地址
选项类型：
str默认值：
127.0.0.1
rcon.port
用于 rcon 连接的端口
选项类型：
int默认值：
25575
rcon.password
用于 rcon 连接的密码
选项类型：
str默认值：
password
插件配置
MCDR 插件相关的配置项
plugin_directories
MCDR 搜索将要加载插件的目录列表
选项类型：
List[str]默认值：
plugin_directories:
- plugins
例如：
plugin_directories:
- plugins
- path/to/my/plugin/directory
- /another/plugin/directory
catalogue_meta_cache_ttl
拉取的插件仓库元信息的缓存有效期
MCDR 会在缓存的有效期内，使用缓存的元信息作为后续与插件仓库有关操作的数据源
选项类型：
float默认值：
1200（20 分钟）
catalogue_meta_fetch_timeout
拉取插件仓库元信息的超时时间，单位：秒
选项类型：
float默认值：
15
catalogue_meta_url
重写用于拉取插件仓库元信息的，指向的 "everything.json" 或 "everything_slim.json" 文件的 URL
若它以 ".gz" (gzip) 或 ".xz" (lzma) 结尾，则将自动应用对应的解压操作
若未指定，则将使用默认的 "https://api.mcdreforged.com/catalogue/everything_slim.json.xz"
取值举例（使用 raw.githubusercontent.com 的原始 URL）：
catalogue_meta_url: 'https://raw.githubusercontent.com/MCDReforged/PluginCatalogue/meta/everything_slim.json.xz'
选项类型：
Optional[str]默认值：空
plugin_download_url
备注
一个将被下载的插件文件是一个 GitHub release 的 asset
重写插件文件的下载 URL。应该是一个合法的 str.format() 字符串
可用的变量
{url}：原始的 GitHub asset 下载链接{repos_owner}：插件的 GitHub 仓库的所有者名{repos_owner}：插件的 GitHub 仓库的仓库名{tag}：与该 release 关联的 git tag 的名字{asset_name}：asset 的名字，即要被下载的插件文件的文件名{asset_id}：GitHub asset ID
作为一个例子，若要使用 ghproxy 进行下载加速，你可以将其设为：
plugin_download_url: 'https://ghfast.top/{url}'
另一个无用的，手动拼接出 GitHub release asset 默认 url 的例子。虽然没什么用，但是一个拿来演示使用方式的好例子：
plugin-download_url: 'https://github.com/{repos_owner}/{repos_name}/releases/download/{tag}/{asset_name}'
若未指定，将直接使用原始的 GitHub 附件下载 URL
选项类型：
Optional[str]默认值：空
plugin_download_timeout
下载插件文件的超时时间，单位：秒
选项类型：
float默认值：
15
plugin_pip_install_extra_args
在插件安装过程中，安装插件依赖的 python 包时，传递给 pip 子进程的额外参数
plugin_pip_install_extra_args: -i https://pypi.tuna.tsinghua.edu.cn/simple --proxy http://localhost:8080
选项类型：
Optional[str]默认值：空
杂项配置
MCDR 的杂项配置
check_update
如果设置为 true，MCDR 将会每隔 24 小时执行一次更新检测
选项类型：
bool默认值：
true
advanced_console
高级控制台的开关，基于 prompt-toolkit
如果你需要重定向 MCDR 的标准输入/输出，或者仅仅是不喜欢这个高级控制台，把它设置为 false
选项类型：
bool默认值：
true
http_proxy, https_proxy
为 MCDR 所有对外的 HTTP 请求的代理设置
如果打算配置，建议同时配置 http_proxy 和 https_proxy 的值
取值举例:
http_proxy: 'http://127.0.0.1:1081'
https_proxy: 'http://127.0.0.1:1081'
http_proxy: 'http://user:pass@192.168.0.1:8888'
https_proxy: 'http://user:pass@192.168.0.1:8888'
选项类型：
Optional[str]默认值：空
telemetry
遥测上报开关
MCDR 会收集一些匿名的遥测数据，包含 MCDR 及运行环境的一些基本信息，目的是为了改进 MCDR。收集的遥测数据不会包含任何个人信息，也不会用于销售或广告的目的
如果你不希望 MCDR 报告任何遥测数据，你可以将此选项设置为 false 来关闭该功能
参见
遥测上报 文档
选项类型：
bool默认值：
true。若环境变量MCDREFORGED_TELEMETRY_DISABLED被设为了true，则默认值将为false
进阶配置
为进阶用户提供的选项
disable_console_thread
设置为 true 时，MCDR 将不会启动控制台线程来处理控制台命令输入
请保持默认值，除非你清楚地知道这是什么
选项类型：
bool默认值：
false
disable_console_color
设置为 true 时，MCDR 将在所有消息打印到控制台之前删除所有控制台字体格式化程序代码
选项类型：
bool默认值：
false
custom_handlers
自定义 服务端处理器 类所组成的列表。这些类应当是 ServerHandler 的子类
这样你就可以在 handler 选项中通过处理器的名称指派其解析标准输出文本
处理器名称通过 get_name() 方法定义
选项类型：
Optional[List[str]]默认值：
custom_handlers:
例如：
custom_handlers:
- handlers.my_handler.MyHandler
下面这个例子中，handlers.my_handler 是包路径，MyHandler 是类名
custom_info_reactors
用于处理 info 对象的自定义 Info 响应器 类所组成的列表。这些类应当是 AbstractInfoReactor 的子类
所有自定义 info 响应器都将注册到反应堆列表中，以处理来自服务端的信息
选项类型：
Optional[List[str]]默认值：
custom_info_reactors:
例如：
custom_info_reactors:
- my.customize.reactor.MyInfoReactor
下面这个例子中，my.custom.reactor 是包路径，MyInfoReactor 是类名
watchdog_threshold
使得 看门狗 认为任务执行者 (task executor) 线程已经未响应所需的时间间隔。将其设为 0 以禁用 看门狗
watchdog_threshold: 10
handler_detection
在默认情况下，MCDR 会在启动时弃用服务端处理器正确性检测，并运行一段时间，用于检测可能出现的 服务端处理器 配置错误
将其设为 false 以禁用服务端处理器检测逻辑，以减少部分 MCDR 开始运行时的性能损耗。这主要在性能分析 MCDR 时使用
选项类型：
bool默认值：
handler_detection: true
调试配置
用于调试 MCDR 的配置
debug
调试日志模式开关。将 all 设置为 true 以启用所有的调试输出。也可以打开部分选项，以启用某些调试输出
默认值：
debug:
all: false
mcdr: false
process: false
handler: false
reactor: false
plugin: false
permission: false
command: false
telemetry: true
write_server_output_to_log_file
启用此功能后，服务器的输出将不仅输出至控制台，也会被写入 MCDR 日志文件（MCDR.log）里。这有助于结合 MCDR 自身的日志来调试 MCDR
选项类型：
bool默认值：
write_server_output_to_log_file: false