附加包故障排除¶
开发附加包时，各种奇怪的问题难免出现。很多看起来复杂的错误其实有固定的排查思路。这一页整理了新手最容易遇到的问题和对应的解决方向——在去社区问之前，先走一遍这些步骤。
快速排查清单¶
如果当前没有明确线索，先按下面顺序快速过一遍：
- 查看内容日志是否有错误与警告。
- 验证JSON语法和字段类型。
- 核对文件位置、文件名和大小写。
- 核对资源包与行为包标识符是否完全一致。
- 判断本次改动是否支持
/reload热重载。 - 必要时完全重启游戏并重新进世界。
第一步：完全重启游戏¶
许多奇怪的表现，包括纹理不更新、实体行为还是旧版本、战利品表不生效等，仅仅通过彻底关闭Minecraft并重新启动就可以解决。退出世界不够，必须把整个游戏进程关掉。
开发目录的优势
把包放在development_resource_packs和development_behavior_packs里开发时，退出世界再重新进入通常可以重载大多数数据驱动内容。但如果你修改了manifest.json或改动了包的文件夹结构，还是要完全重启。
第二步：开启并查看内容日志¶
内容日志是排查附加包问题最重要的工具。Minecraft每次加载世界时都会把检测到的问题写入日志，包括：
- 错误的纹理路径；
- 拼写错误的组件名称；
- 不合法的JSON结构；
- 格式版本不匹配；
- 找不到引用的文件。
如何开启¶
进入游戏设置 > 创作者，把内容日志GUI和内容日志文件两个选项都打开。开启后，加载世界时如果包有问题，屏幕上会弹出日志面板；游戏内按Ctrl＋H也可以随时打开。
日志不会自动清除
内容日志会把每次加载世界的内容追加进去。查问题时要注意时间戳，不要把旧错误当作当前问题来排查。
日志文件位置¶
如果想查看完整的历史日志，文件保存在以下位置：
- Windows：
%localappdata%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\logs - Android：
/storage/emulated/0/Android/data/com.mojang.minecraftpe/files/games/com.mojang/logs
第三步：验证JSON格式¶
JSON格式错误会导致整个文件无法被解析，且通常不会给出明显的行为异常——包只是"什么都没发生"。
最快速的验证方式：
- 使用支持JSON语法高亮的编辑器（如Visual Studio Code），它通常会在语法错误的行旁边显示红色波浪线；
- 把文件内容粘贴到jsonlint.com，它会精确指出错误的行号和类型。
常见的JSON错误包括：
- 数组或对象的最后一个元素后面多了逗号（例如
"value": 1,}）； - 字符串值没有用双引号包裹；
- 括号不配对，少了
}或]； - 使用了单引号而不是双引号。
第四步：检查文件结构和命名¶
基岩版只会在约定目录下查找约定类型的文件。路径不对或文件夹名拼错时，游戏通常直接忽略该文件，不给任何报错。常见问题如下：
| 错误类型 | 例子 |
|---|---|
| 文件夹名拼错 | function（正确是functions） |
| 文件放错了包 | 把行为包的entities文件夹放进了资源包 |
| 标识符缺少命名空间 | 写成ghost而不是demo:ghost |
| 纹理引用带了扩展名 | textures/items/coin.png（应为textures/items/coin） |
| 引用路径大小写不一致 | 文件名是Ghost.png但引用写的是ghost.png |
另外请确认资源包与行为包中同一对象的标识符完全一致。例如行为包中写demo:robot，资源包客户端实体也必须写demo:robot。只要命名空间或大小写不一致，模型、纹理、动画引用都会失效。
第五步：确认两个包都已激活¶
测试世界必须同时激活资源包和行为包。只激活其中一个会导致另一个包的内容无效。例如，只激活行为包时，实体的客户端定义（在资源包中）无法加载，实体将在游戏中不可见。
常见症状速查¶
| 症状 | 高概率原因 | 首选修复方向 |
|---|---|---|
| 实体生成后立刻坠落 | 缺少minecraft:physics或碰撞设置不完整 | 为实体补齐物理与碰撞相关组件 |
| 实体不动 | 缺少移动组件或AI意向 | 检查minecraft:movement、导航与行为组件 |
| 实体紫黑棋盘格 | 纹理路径错误或资源包标识符不匹配 | 逐项核对客户端实体、渲染控制器和纹理路径 |
| 自定义方块不掉落 | 战利品表路径错误或文件不存在 | 检查minecraft:loot路径和战利品表JSON |
| 配方无法合成 | 配方类型、标签或标识符写错 | 核对minecraft:recipe_*类型和tags |
| 脚本重载后逻辑触发次数翻倍 | 事件重复订阅 | 增加初始化保护并避免重复注册 |
第六步：检查UUID与依赖¶
manifest.json中最容易漏的点有两类：
- 不同包或不同模块误用了同一个UUID。
- 脚本依赖写法错误，把
module_name写成了uuid依赖格式。
这两类错误都可能导致“包看起来导入成功但功能不执行”。
参考原版文件¶
遇到不知道怎么写的字段时，最可靠的参考就是游戏自带的原版文件。从Mojang官方GitHub下载最新版原版资源包和行为包，找到与你要做的内容最相近的原版文件，对照学习。
原版文件里几乎包含了附加包系统的所有功能的实际使用示例，是最权威的参考。
使用JSON架构校验¶
JSON架构是对JSON文件结构的约束定义。如果在编辑器里配置了基岩版的JSON架构，编辑器会实时提示字段名拼写错误、缺失必填字段或值类型不对等问题。具体配置方法参考配置JSON架构校验。
仍然找不到原因？¶
如果以上步骤都确认无误但问题仍然存在，可以去社区寻求帮助。提问时请提供：
- 你使用的游戏版本；
- 相关的JSON文件内容；
- 内容日志中的完整报错信息。