本文全文授权搬运自 MCDReforged 官方文档的《快速上手》章节：https://docs.mcdreforged.com/zh-cn/latest/quick_start/index.html
若希望获得更好阅读体验（代码框、表格、超链接、asciinema 动画等），以及更为长期的维护支持，请阅读官方文档
MCDR 官网 + 插件仓库：https://mcdreforged.com/zh-CN
MCDR 官方文档：https://docs.mcdreforged.com/zh-cn
MCDR 是什么
MCDReforged (MCDR, 下同) 是一个管理 Minecraft 服务器的工具，拥有自定义插件系统。完全无需修改 Minecraft 服务器本身
游戏内计算器，玩家高亮，计分板操作，结构文件管理，备份/回档... 你可以用 MCDR 和其插件控制整个 Minecraft 服务器
特别感谢 chino_desu（https://github.com/kafuuchino-desu）和他的 MCDaemon 1.0（https://github.com/kafuuchino-desu/MCDaemon）提供如此炫酷的点子
优势
纯净
MCDR 运行于服务端之上，不需要对服务端进行修改，从而保证一切都是 原版 的
插件系统
MCDR 拥有丰富的 社区插件生态（https://mcdreforged.com/zh-CN/plugins）。小至计算器、高亮玩家、b 站弹幕姬，大至操控计分板、管理结构文件、自助备份回档，都可以通过 MCDR 及相配套的插件实现
支持热重载，无需关闭服务器即可更新插件
兼容性
支持大多数流行服务端 (Vanilla, Fabric, Spigot, Paper 等)
支持多平台 (Windows, Linux, Mac 等)
它是如何工作的
简单来说: MCDR 就像一个盯着服务端控制台看的小机器人，快速响应服务端输出，并为用户输入命令
MCDR 使用 Popen（https://docs.python.org/3/library/subprocess.html#subprocess.Popen）来启动服务端软件作为子进程，因此它能够控制服务端的输入输出流
由于 Minecraft 服务端的控制台输出格式稳定，并且包含大量有用的信息，例如玩家聊天消息，MCDR 能够解析和分析服务端输出，将它们抽象为不同的事件，并将它们分派给插件以进行响应
借助 Minecraft 命令系统，MCDR 可以通过标准输入流发送 Minecraft 命令以操作 Minecraft 服务端
安装
踏上我们的旅程，从安装 MCDR 开始
我们假设你对 Python 和 pip 有一些基本的了解。不了解也没关系，善用搜索引擎
环境依赖
MCDR 使用 Python 3 编写和运行。确保你的 Python 版本至少为 3.8
详情如下表所示
MCDR < 2.10：Python >= 3.6
MCDR >= 2.10：Python >= 3.8
（未来）MCDR >= 2.15：Python >= 3.9
先等等
在一些教程中，你可能会听说要从 Github 下载 zip 文件并解压来使用 MCDR
然而，那并不是安装 MCDR 的正确方式——那些教程已经过时了。MCDR 自 2021 年初的 v1.0 版本开始，就不再使用源码安装了
注意：不要 下载 MCDR 的源码并直接运行，除非你是 MCDR 的开发者，并且你知道你在干什么
使用 pip 安装
MCDR 已上传至 PyPI（https://pypi.org/project/mcdreforged）。它理应能由如下命令安装
pip install mcdreforged
并用如下命令升级：
pip install mcdreforged -U
验证安装是否成功：
mcdreforged
对于国内用户，若在 pip 安装时出现了下载缓慢、网络不畅等网络问题，可以参考下文的“加速安装”小节来解决
外部管理的环境
如果你使用的是 Windows，上述命令应当能正常工作，MCDR 将被安装到全局环境中，你可以忽略本节内容
但是，在 Linux 和 Mac OS 中，我们不建议全局（使用 root）安装 MCDR，因为它可能会与其他 Python 包产生冲突，并可能影响系统依赖
全局安装也使得版本管理变得困难，并且需要管理员权限，增加了安全风险
全局安装甚至可能导致 externally-managed-environment 错误
详见 PEP 668（https://peps.python.org/pep-0668/）
为了安全起见，最好将 MCDR 安装在一个与全局环境相隔离的环境中。有如下几种方案可供参考：
使用 pipx
也许是对大多数用户而言最简单的解决方案，但需要使用第三方工具 pipx。pipx 专为在隔离环境中安装和运行 Python 应用程序而设计
请先参考其官方文档（https://pipx.pypa.io/stable/#install-pipx）安装 pipx
然后再使用 pipx 安装 MCDR：
pipx install mcdreforged
在 MCDR 发布新版本后，你可以通过以下命令升级：
pipx upgrade mcdreforged
如此一来，MCDR 将被安装在一个 pipx 管理的隔离环境中。要将 Python 包安装到此环境中，不建议使用 pip install <包名称>，而应该使用：
pipx inject mcdreforged <包名称>，例如 pipx inject mcdreforged requests
或 pipx inject mcdreforged -r requirements.txt
当然，也可以用 !!MCDR plg 命令（https://docs.mcdreforged.com/zh-cn/latest/command/mcdr.html#plugin-management）更轻松地安装插件及其依赖
使用虚拟环境
这是最原生但也更复杂的方法，你可以创建一个虚拟环境，并在其中安装 MCDR
通过以下命令创建虚拟环境：
python3 -m venv <venv directory>
例如使用 venv 作为虚拟环境的部署路径：
python3 -m venv venv
然后通过以下命令激活虚拟环境（可以去这里复制命令：https://docs.python.org/zh-cn/3/library/venv.html#how-venvs-work）：
参见：Python 文档: 虚拟环境是如何实现的（https://docs.python.org/zh-cn/3/library/venv.html#how-venvs-work）
在虚拟环境激活后，你的终端环境中应当出现 (venv) 前缀，如
(venv) $ pip -V
然后，你可以直接使用 pip 安装 MCDR：
pip install mcdreforged
在 MCDR 发布新版本后，你可以通过以下命令升级：
pip install mcdreforged -U
使用 bash 的动画演示：
备注：这样一来，每当你需要使用 MCDR，或要为 MCDR 插件安装 Python 包依赖时，你都需要激活虚拟环境。更多信息，参见 Python 文档：虚拟环境的创建（https://docs.python.org/zh-cn/3/library/venv.html）
使用 Docker
MCDR 还提供了 Docker 镜像。参见 Docker（https://docs.mcdreforged.com/zh-cn/latest/docker.html）一章
除了最基础的 MCDR 镜像外，MCDR 还提供了预安装了额外 Python 包 / OpenJDK 的镜像变体
与上述两种方法相比，Docker 的学习路线更曲折，但更适合一些高级用法
系统包管理器
您可以在一些系统包仓库（例如 AUR）中找到 MCDR。但，非常不建议 使用系统包管理器来安装 MCDR。系统包安装不仅与全局 pip 安装有同样的问题，而且很难管理 MCDR 插件的依赖
加速安装
中国用户可以使用 PyPI 镜像，来加速 pip 和 pipx。例如使用清华大学 TUNA 镜像（https://mirrors.tuna.tsinghua.edu.cn/help/pypi/）
长话短说，只需在命令中添加 -i <index-url> 参数，即可使用 TUNA 镜像：
pipx install -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged
pipx upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged -U
你也可以通过以下命令设置全局索引，一劳永逸：
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
启动！
现在你已经安装好了 MCDR，是时候启动它了
备注：MCDR 最常见的用途是控制 Minecraft 服务器，我们也就以此为例
在用 MCDR 管理 Minecraft 服务器前，建议对常见的 Minecraft 服务端有些基础了解
换句话说，请先了解：
常见的 Minecraft 服务端：有哪些，该如何配置（了解其中一种即可）
Minecraft 服务端的启动命令：是什么，启动参数分别是什么意思
服务端控制台：它会输出什么，能接受什么命令
如何管理服务器：配置文件，mod / 插件 等
不了解也没关系，请善用搜索引擎
准备
要用 MCDR 管理 Minecraft 服务器，你首先需要 配置好 一个 Minecraft 服务端
例如，这是典型的原版 Minecraft 服务端目录结构：
可以使用以下命令启动它：
java -Xms1G -Xmx2G -jar minecraft_server.jar nogui
当然，你也可以选择其他服务端，如 Fabric、Spigot、Paper 等
小技巧：在引入 MCDR 之前，请先配置并调试好服务端。否则，你将很难区分由 MCDR 和由服务端引起的问题
MCDR 是为 Minecraft Java 版常见服务端而诞生的。大多数插件以此为前提。当然，如果你不需要使用为 Java 版服务器设计的插件生态系统，那用 MCDR 跑啥都行
初始化
假设你要在名为 my_mcdr_server 的文件夹中启动 MCDR，那么你可以运行以下命令来初始化 MCDR 环境：
cd my_mcdr_server
mcdreforged init
MCDR 将生成一个如下所示的默认文件结构：
动画演示：
配置
服务端
还记得你准备的服务端吗？把它整份放到 server 文件夹中
配置文件
然后，你需要编辑 config.yml 文件来配置 MCDR。详见 配置（https://docs.mcdreforged.com/zh-cn/latest/configuration.html）一章
对于大多数用户来说，有 4 个需要注意的配置项：
language：MCDR 使用的语言：https://docs.mcdreforged.com/zh-cn/latest/configuration.html#language
start_command：MCDR 启动服务端的命令：https://docs.mcdreforged.com/zh-cn/latest/configuration.html#start-command
handler：MCDR 处理服务端输出的方式：https://docs.mcdreforged.com/zh-cn/latest/configuration.html#handler
encoding, decoding：MCDR 编/解码 服务端 输入/输出流 的方式：https://docs.mcdreforged.com/zh-cn/latest/configuration.html#encoding-decoding
请仔细阅读这几节，确保填写正确
例如，对于 Java 21 的 Minecraft 1.21 原版服务端，需要关注的部分如下：
start_command: java -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -Xms1G -Xmx2G -jar minecraft_server.jar nogui
handler: vanilla_handler
encoding: utf8
decoding: utf8
如果你产生了 “为什么这命令相比上面的例子长了这么多” 的疑问，请再读读 encoding, decoding（
ttps://docs.mcdreforged.com/zh-cn/latest/configuration.html#encoding-decoding）一节
启动！
现在，你应该能够启动 MCDR，并且它应该能够正确地处理服务端
mcdreforged
如上配置的动画演示：
也请在游戏中测试 MCDR：
更进一步
现在，你已经了解了 MCDR 的基本知识。接下来呢？
插件
插件让 MCDR 更强大。你可能想：
看看 插件仓库（https://mcdreforged.com/zh-CN/plugins），找些有趣的插件
使用 !!MCDR plg（https://docs.mcdreforged.com/zh-cn/latest/command/mcdr.html#plugin-management）命令来搜索并一键安装插件
如果你有兴趣自己开发一个插件：
创建你自己的插件（https://docs.mcdreforged.com/zh-cn/latest/plugin_dev/basic.html），并将其发布到插件仓库中（https://docs.mcdreforged.com/zh-cn/latest/plugin_dev/plugin_catalogue.html）
官方的示例插件（https://github.com/MCDReforged/ExamplePlugin）和插件模板（https://github.com/MCDReforged/PluginTemplate）或能助你一臂之力
代码参考（https://docs.mcdreforged.com/zh-cn/latest/code_references/index.html）也许能助你理解 MCDR 的接口
查看热门插件，甚至 MCDR 本身的源代码，以了解更多
命令
MCDR 有一个内置的命令系统。MCDR 的命令常以 !! 开头。上面提到的 !!MCDR plg 就是一个内置命令
详见命令（https://docs.mcdreforged.com/zh-cn/latest/command/index.html）一章
权限
MCDR 有一个用于控制命令执行的权限系统。例如，大部分 !!MCDR 命令只有 level 3 (管理员) 用户才能执行。
目前，权限系统比较简单，但足以应对大部分情况
详见权限（https://docs.mcdreforged.com/zh-cn/latest/cli/index.html）一章
命令行接口
MCDR 提供了一个命令行接口，内含不少实用工具。例如，你可以在不启动服务器的情况下管理插件
详见命令行接口（https://docs.mcdreforged.com/zh-cn/latest/migrate/index.html）一章
社区
我们在 Github 上有一个组织，托管了 MCDR 项目的绝大部分源码：https://github.com/MCDReforged
迁移
如果你曾是 MCDR 旧版本的用户，你可能想看看 迁移指引（https://docs.mcdreforged.com/zh-cn/latest/migrate/index.html）
祝你玩的开心！
故障排除
遇到问题？这里有一些常见的问题和解决方案
MCDR 无法启动
mcdreforged 不是内部或外部命令
若你通过 pipx 安装了 MCDR，确保 pipx 应用程序目录在你的 PATH 中
若你通过 pip 安装了 MCDR，尝试明确指定 Python 解释器来启动 MCDR：python -m mcdreforged，以避免出现使用了错误的 Python 解释器的情况
若你通过 pip 全局安装了 MCDR，确保 pip 已安装脚本的目录在你的 PATH 中
若你通过 pip 在 venv 中安装了 MCDR，确保你激活了 venv
如果你通过系统包管理器安装了 MCDR... 不要通过系统包管理器安装 MCDR
Python 抛出错误
请确保你正确地安装了 MCDR。不要从源码启动 MCDR
尝试重新安装 MCDR，看看问题是否依然存在
若你通过 pip 在 venv 中安装了 MCDR，确保你激活了 venv
使用 which mcdreforged (Windows 下使用 where mcdreforged)，看看调用了哪个可执行文件
服务器无法启动
检查你的启动命令
检查 Java 是否已安装并添加到 PATH 中
尝试使用你配置的命令直接启动服务端
如果你将启动命令指向批处理或 shell 脚本，尝试直接使用实际命令而不是脚本
详见 start_command（https://docs.mcdreforged.com/zh-cn/latest/configuration.html#start-command）一节
乱码 / UnicodeDecodeError
这通常是控制台编解码异常引起的
MCDR 默认使用 UTF-8 编码和解码，不妨尝试在服务端相关的所有地方都使用 UTF-8。参见 encoding, decoding（https://docs.mcdreforged.com/zh-cn/latest/configuration.html#encoding-decoding）一节
命令不工作
所有命令在游戏内都不响应，但控制台里正常
某些命令对特定玩家执行不正确
MCDR 通过监听服务端控制台输出来处理命令，请确保你使用了正确的 服务端处理器（https://docs.mcdreforged.com/zh-cn/latest/configuration.html#handler）
你的服务端可能意外地与处理器不兼容：
也许，你的服务端比较特别，内置处理器均不兼容
也许，你的服务端输出与默认状态不同。例如，如果你允许非 Mojang 命名规则（[A-Za-z0-9_]{3,16}）的玩家名，处理器将无法识别。例如：
[09:00:00] [Server thread/INFO]: <Steve.the.Warrior> Hello
[09:00:00] [Server thread/INFO]: <史蒂夫> hello
也许，你的服务端输出被插件或模组（例如：玩家称号/职业，更好的控制台）修改了，导致处理器无法识别。禁用所有插件和模组，看看问题是否解决。例如：
[09:00:00] [Server thread/INFO]: <[Warrior]Steve> Hello
(09:00:00) INFO | Steve: hello
这些输出均与原版服务端的输出（如下）不同
[09:00:00] [Server thread/INFO]: <Steve> Hello
如果你的服务端存在上述问题之一，你可能需要自定义服务端处理器（https://docs.mcdreforged.com/zh-cn/latest/customize/handler.html#server-handler）
某些插件命令在游戏和控制台中都无法使用
某些插件命令在所有条件下都执行不正确
检查插件是否正确启用和加载。检查日志，看看是否有与插件相关的错误或警告，若有则请仔细阅读相关输出
查看插件的 README 或文档，看看它是否有任何特殊要求。有些插件可能需要额外权限或配置。检查并确保插件配置文件已被正确填写
有些插件可能与其它插件冲突。尝试禁用其它插件，看看问题是否解决
如果问题仍然存在，尝试向插件的作者或社区报告
使用 MCSManager 运行
警告：这部分内容可能过时。若你遇到任何问题，不要向 MCDR 报告。
更多信息，请与 MCSManager 社区联系：Github 仓库（https://github.com/MCSManager/MCSManager），MCSManager 文档（https://docs.mcsmanager.com/）
MCDR 并未专门适配 MCSManager
不过，如果你始终使用 UTF-8，并在 MCSManager 中启用 仿真终端，MCDR 应该能正常工作，并具有完整功能
若你关闭了 仿真终端，请将 advanced_console（https://docs.mcdreforged.com/zh-cn/latest/configuration.html#advanced-console）设置为 false
联系我们
如果以上方案无法解决你的问题，请联系我们可爱的社区
还请注意，在提问或报告问题之前，请：
先尝试自己搜索并研究
用一个简短的句子概括你的问题
帮助他人重现问题：
构建最小复现示例（https://stackoverflow.com/help/minimal-reproducible-example）
提供完整的日志和环境，不要提供非必要的图片。若日志太长，请将其作为附件发送，或使用 https://mclo.gs/ 或 https://pastebin.com/ 等服务来提供。记得清理日志中的敏感信息
提问之前校对你写的问题描述，确保语意清晰无歧义
提问之后，积极回应他人反馈
参见：Stack Overflow: 如何正确地提问？（https://stackoverflow.com/help/how-to-ask）
