调试与热更新
写完脚本按下运行，结果什么都没发生——这在 Mod 开发中太常见了。问题可能是拼写错误、事件名写错、回调参数取错，但没有有效的调试手段，你只能靠猜。本节将系统介绍从日志打印到断点调试的全套工具链，让你快速定位和修复问题。
你将学到
print和mod_log两种日志打印方式- 调试工具窗口的使用（搜索、过滤、实时执行 Python）
- 热更新的使用方法和限制
- VS Code 断点调试（MCDev Tools 插件）
- PyCharm 断点调试（MC Studio Helper 插件）
- 常见脚本错误的排查方法
日志打印
日志打印是最基础也最常用的调试手段。中国版 ModSDK 支持两种方式。
方式一：print（简单直接）
print "===== ServerSystem init ====="
print("玩家加入：{}".format(playerId))
print("物品信息：", itemDict)print 的输出会显示在调试工具窗口中。建议加上唯一前缀（如 [TomatoMod]），方便在大量日志中搜索：
print("[TomatoMod] 绿宝石数量变化：{} -> {}".format(oldCount, newCount))方式二：mod_log（推荐）
mod_log 是官方提供的日志模块，支持分级输出，在调试工具中会以不同颜色显示：
from mod_log import logger
logger.debug("调试信息：slot=%d", slot) # [DEBUG] 灰色
logger.info("玩家 %s 加入游戏", playerId) # [INFO] 白色
logger.warning("物品不存在：%s", itemName) # [WARNING] 黄色
logger.error("创建 UI 失败！") # [ERROR] 红色该用哪个？
开发阶段用 print 快速查看变量没问题。但正式项目建议用 mod_log，因为：
- 支持日志级别过滤，上线前可以只保留
warning以上 - 在调试工具中有颜色区分，一眼看出严重程度
mod_log和logging都在 Python 模块白名单中，可安全使用
实用打印技巧
# 打印事件的全部参数（快速了解有哪些字段）
def OnPlayerAttack(self, args):
print("[TomatoMod] PlayerAttackEntityEvent args:", args)
# 打印组件返回值（确认 API 是否正常工作）
items = itemComp.GetPlayerAllItems(
serverApi.GetMinecraftEnum().ItemPosType.INVENTORY
)
print("[TomatoMod] 背包物品：", items)
# 在关键流程加入检查点
print("[TomatoMod] >>> 进入 _CountEmeralds")
# ...逻辑代码...
print("[TomatoMod] <<< 退出 _CountEmeralds, total=", total)调试工具
从 MCStudio 启动开发测试时，调试工具会自动打开。它已经取代了旧版"脚本测试日志"，成为官方主力调试工具。
主要功能
| 功能 | 说明 |
|---|---|
| 日志查看 | 实时显示 print 和 mod_log 输出，支持颜色分级 |
| 关键字搜索 | 输入关键字按 Enter 跳转，支持正则、大小写敏感、全字匹配 |
| 标签过滤 | 按 Developer / Engine / INFO 等标签筛选日志 |
| 暂停/恢复 | 暂停滚动时日志不丢失，恢复后自动补全 |
| 错误跳转 | 点击错误日志中的文件链接，IDE 自动跳转到对应代码行 |
| Python 执行 | 在输入框中写 Python 代码，选择"客户端运行"或"服务端运行"实时执行 |
| 组件同步 | 将修改后的代码同步到手机测试客户端 |
实时执行 Python
这是调试工具最强大的功能之一。在游戏运行时，你可以直接在输入框中执行 Python 代码：
# 在"服务端运行"模式下执行
import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreateGame(serverApi.GetLevelId())
print(comp.GetAllScoreboardObjects())这样可以在不重启游戏的情况下验证 API 调用结果、查看游戏状态，甚至临时修复数据。
注意
实时执行的代码只在当前会话有效，不会保存。它适合快速验证和排查，不要用来替代正式代码。
连接手机测试
调试工具支持连接手机测试客户端查看远程日志：
- 确保手机和电脑在同一 WiFi 网络
- 在手机上启动开发者测试包，进入主界面
- 在调试工具中点击"客户端IP连接"，输入手机 IP 地址
- 连接成功后，手机端的日志会实时显示在调试工具中
热更新
热更新让你修改代码后不需要重启游戏就能看到效果，极大提升开发效率。
使用方法
- 游戏保持运行状态
- 在 IDE 中修改 Python 文件并保存
- 切换回 MCStudio 或游戏窗口
- 调试工具显示："正在重载相关的Python模块"
- 修改立即生效
快捷操作
- 在游戏中按 R 键可手动触发热重载脚本
- 按小键盘 0 键可重载整个存档
- ModPC 开发菜单（右上角）也有"热更"按钮
热更新的限制
热更新只对函数体内部修改可靠生效。以下修改需要退出重进存档：
| 修改类型 | 热更新是否生效 |
|---|---|
| 修改函数内部实现 | 生效 |
| 修改全局变量 | 不一定生效 |
| 新增类 | 不一定生效 |
| 新增文件 | 不一定生效 |
修改 __init__ 中的监听注册 | 不生效（需要重新初始化） |
| 修改 JSON 资源文件 | 不生效（需要重启） |
热更新失败怎么办？
如果修改后没有生效，保存文件后退出到主菜单再重新进入存档，即可完全重新加载所有 Mod 代码。这是最可靠的"万能方案"。
断点调试
日志打印只能看到你预设的输出，而断点调试可以让程序在指定位置暂停，实时查看所有变量的值、调用栈、执行路径。这是定位复杂 Bug 的终极手段。
中国版 ModPC 开发包已支持基于 ptvsd / DAP（Debug Adapter Protocol） 的 Python 断点调试。
VS Code：MCDev Tools 插件（推荐）
MC Dev Tools 是一个一站式的 VS Code 调试插件，支持一键启动游戏并附加调试器。
安装：
- 在 VS Code 扩展商店搜索
MC Dev Tools（发布者：dofes）并安装 - 确保已安装 Python 扩展
配置 launch.json：
在项目根目录的 .vscode/launch.json 中添加：
{
"version": "0.2.0",
"configurations": [
{
"type": "mcdev-tools",
"request": "launch",
"name": "Minecraft Python Debug",
"timeout": 60000,
"dapConfig": {
"justMyCode": false
}
}
]
}使用：
- 在代码中点击行号左侧设置断点（红色圆点）
- 按 F5 选择 "Minecraft Python Debug" 配置
- 插件自动启动 mcdk → 启动游戏 → 附加调试器
- 当代码执行到断点时，VS Code 会自动暂停，左侧面板显示：
- 变量：当前作用域的所有变量和值
- 调用栈：函数调用链路
- 监视：添加自定义表达式实时监控
调试控制：
| 操作 | 快捷键 | 说明 |
|---|---|---|
| 继续 | F5 | 运行到下一个断点 |
| 单步跳过 | F10 | 执行当前行，不进入函数内部 |
| 单步进入 | F11 | 进入函数内部 |
| 单步跳出 | Shift+F11 | 执行完当前函数，返回调用处 |
注入模式（备选）
如果游戏已经在运行，可以用注入模式附加调试器：
{
"type": "mcdev-tools-inject",
"request": "launch",
"name": "Minecraft Debug (Inject)",
"port": 5678,
"dapConfig": {
"justMyCode": false
}
}插件会查找运行中的 Minecraft 进程，注入 debugpy 并连接。
PyCharm：MC Studio Helper 插件
MC Studio Helper 为 PyCharm 用户提供了类似的调试体验。
环境要求：
- PyCharm 2025.1 及以上版本
- ModPC 开发包 3.7.0.222545 及以上版本
- LSP4IJ 插件（随 MC Studio Helper 自动安装）
安装：
- 打开 PyCharm → Settings → Plugins
- 搜索
MC Studio Helper并安装 - 重启 PyCharm
第一步：添加运行配置
- 点击右上角 Debug 按钮旁的 "Edit Configurations..."
- 点击 + 添加 MC Studio Helper 类型的运行配置
- 填写配置信息（开发包路径等）
第二步：运行游戏
点击运行按钮启动游戏，日志输出界面会自动打开。此时可以：
| 操作 | 方式 |
|---|---|
| 热重载脚本 | 切回游戏后按 R 键 |
| 重载存档 | 按小键盘 0 键 |
| 跳转到错误代码 | 点击日志中的文件链接 |
第三步：断点调试
- 确认日志开头有调试器就绪提示
- 再添加一个 调试适配器协议（DAP） 类型的运行配置
- 点击"创建新服务器" → 选择 Python 模板
- 设置：调试模式 = 附加，地址 =
127.0.0.1，端口 =5678 - 填写 DAP 参数 JSON：
{
"name": "Attach",
"type": "python",
"request": "attach",
"redirectOutput": true,
"connect": {
"host": "127.0.0.1",
"port": 5678
},
"pathMappings": [
{
"localRoot": "${workspaceFolder}",
"remoteRoot": "${workspaceFolder}"
}
],
"debugOptions": [
"ShowSpecialMembers",
"ShowPrivateMembers",
"ShowFunctionMembers",
"ShowBuiltinMembers"
]
}- 以**调试模式（Debug）**运行该配置
- 在 PyCharm 中设置断点：点击行号左侧两次（第一次点击空白处，第二次点击行内）
- 当断点命中时，调试窗口显示变量、调用栈等信息
- 按 F9 继续运行
PyCharm 断点的特殊操作
PyCharm 中使用 DAP 调试时，设置断点需要点击两次才能生效，这与 VS Code 单击设置断点不同。
常见错误排查
错误日志怎么读
Python 错误会在调试工具中显示完整的 traceback（回溯信息）：
Traceback (most recent call last):
File "Scripts/server/ServerSystem.py", line 42, in OnInventoryChanged
count = self._CountEmeralds(playreId)
^^^^^^^^^
AttributeError: 'TomatoServerSystem' object has no attribute '_CountEmeralds'阅读顺序：
- 从下往上读——最后一行是错误类型和描述
- 倒数第二行是出错的代码
- File 行告诉你文件名和行号
常见错误类型
| 错误 | 原因 | 解决 |
|---|---|---|
ImportError | 模块名/路径拼写错误 | 检查文件名和 import 路径是否一致 |
NameError | 使用了未定义的变量 | 检查变量名拼写，确认作用域 |
AttributeError | 对象没有这个属性/方法 | 检查方法名拼写，确认 API 是否存在 |
TypeError | 参数类型不对或数量不对 | 检查 API 文档中的参数要求 |
KeyError | 字典中不存在这个键 | 用 .get(key, default) 安全取值 |
SyntaxError | 语法错误（缩进、括号等） | 检查代码缩进（Python 2 用空格不用 Tab 混用） |
排查清单
当脚本"什么都没发生"时，按以下顺序排查：
- 检查日志窗口——有没有报错？如果有，从下往上读 traceback
- 确认事件名拼写——
InventoryItemChangedServerEvent这种长名称很容易打错 - 确认监听注册——
ListenForEvent是否在__init__中被调用？ - 加 print 检查点——在回调函数第一行加
print(">>> 事件触发了")，确认回调是否被调用 - 检查参数名——事件回调的字典 key 是否正确（如
playerId不是playerID） - 确认 mod.json 注册——服务端和客户端的 System 是否在 mod.json 中正确注册
- 检查热更新限制——如果修改了
__init__或新增文件，需要退出重进存档
最有效的调试策略
先缩小范围，再定位细节。 从事件回调入口开始加 print，确认事件是否触发、参数是什么，然后逐步深入。大部分问题在前 3 步就能发现。断点调试留给复杂的逻辑问题。
打包错误速查
提交审核时的常见打包错误：
| 错误码 | 含义 | 解决 |
|---|---|---|
| 8 | Python 脚本打包错误 | 检查语法错误，确保 Python 2 兼容 |
| 10 | 缺少 manifest.json | 确认 behavior_packs 中有 manifest.json |
| 16 | 文件名包含中文或特殊字符 | 文件名只用英文、数字、下划线 |
| 18 | 使用了未授权的 API / 语法 | 检查 Python 模块白名单 |
| 25 | JSON 文件编码错误 | 确保所有 JSON 文件为 UTF-8 编码 |
| 37 | manifest.json 缺少 min_engine_version | 添加正确的 min_engine_version 字段 |
小结
| 要点 | 说明 |
|---|---|
| 日志打印 | print 快速调试，mod_log 分级输出（推荐正式项目使用） |
| 调试工具 | MCStudio 自动启动，支持搜索、过滤、实时执行 Python |
| 热更新 | 修改函数体后保存即生效，新增类/文件/全局变量需退出重进 |
| VS Code 断点调试 | 安装 MC Dev Tools 插件，F5 一键启动调试 |
| PyCharm 断点调试 | 安装 MC Studio Helper 插件，DAP 附加模式调试 |
| 读错误日志 | 从下往上读 traceback，最后一行是错误类型 |
| 排查顺序 | 日志报错 → 事件名 → 监听注册 → print 检查点 → 参数名 → mod.json |
| 打包错误 | 语法错误(8)、缺 manifest(10)、中文文件名(16)、编码(25) |
恭喜！你已经完成了 Python 脚本开发的全部 9 节教程。从环境搭建、CS 架构、事件系统、组件调用、跨端通信、UI 界面、计分板实战到调试技巧，你已经具备了独立开发中国版 Mod 的核心能力。接下来可以回到开发指南深入学习更多高级主题，或者直接动手开发你自己的作品！