先给结论
基岩版服务端通过 manifest 中的 UUID 与版本号识别内容包,通过世界目录里的引用文件决定世界启用哪些包。包的身份由 UUID 决定,包的新旧由 version 决定,二者任何一项处理不当,都会出现更新不生效、包冲突或客户端使用旧缓存的问题。把内容包当成需要版本管理的发布物,而不是随手替换的文件夹,才能稳定迭代玩法。
一、manifest 中的三个关键字段
header 的 uuid 是内容包的身份标识,同一个包在整个生命周期里应保持不变,换了 UUID 就等于发布了一个新包。
header 的 version 表示包的版本,通常是三段数字。更新内容时提升版本号,服务端与客户端才能识别这是同一个包的新版本。
modules 中每个模块也有自己的 uuid 和 version,模块 uuid 同样需要唯一,且不能与 header uuid 相同。
min_engine_version 用于声明包需要的最低引擎版本,写得过高会导致旧版客户端无法使用,写得过低又可能使用到不兼容的写法。
这几个字段应当被视为发布元数据,由专人维护,而不是每个修改者随意改动。
二、世界如何引用内容包
世界目录中有两类引用文件,分别记录该世界启用的行为包与资源包,内容是包的 pack_id 与 version 列表。
服务端启动时根据这些引用找到对应的包。如果引用的版本与包目录中的实际版本不一致,包可能无法被正确加载。
因此更新包时,需要同步更新世界引用文件中的版本号,或者使用与引用一致的版本。
引用文件是 JSON 格式,手工编辑时同样要保证语法合法,否则整份引用可能失效,表现为世界中所有包都不生效。
建议把引用文件也纳入备份与版本记录,它和包本身一样决定了世界的玩法状态。
三、UUID 冲突与重复包
最常见的错误是复制一个现成的包作为模板,却忘了更换 UUID。两个包使用同一身份时,后加载的那个会被忽略或覆盖。
表现往往很隐蔽:日志里可能只有一条警告,游戏里则是某个功能完全没有出现。
排查方式是列出服务器上所有包的 header uuid 与模块 uuid,检查是否存在重复。
生成 UUID 时使用标准工具随机生成,不要手工修改几位数字凑一个新值。
对团队维护的包,建议建立一张包清单:名称、header uuid、当前版本、负责人、依赖关系。
四、客户端缓存问题
玩家进入服务器时会下载服务器提供的资源包,客户端会根据包身份与版本判断是否需要重新下载。
如果更新了包内容却没有提升版本号,部分客户端会继续使用本地缓存的旧版本,玩家看到的仍是旧贴图或旧界面。
正确做法是每次发布内容变更都提升版本号,并同步更新世界引用。
遇到个别玩家仍显示旧内容时,可以引导其清理客户端缓存的资源包,但这只是补救,根本解决仍是规范版本号。
在更新公告中写明包版本,玩家可以自行判断是否已更新成功。
五、依赖与加载顺序
行为包与资源包之间、多个包之间可能存在依赖关系,依赖通过 dependencies 字段声明。
依赖的包缺失或版本不匹配时,主包可能部分功能失效,排查时要先确认依赖是否齐全。
多个资源包覆盖同一文件时,加载顺序决定最终显示效果,顺序错误会出现贴图被意外覆盖。
建议尽量减少包之间的隐式覆盖,把同一类资源集中在一个包中维护。
依赖关系应当写入包清单,升级任何一个包前先检查谁依赖它。
六、发布流程建议
在测试世界中完成修改并验证,确认功能、贴图与日志都正常。
提升 header version,必要时同步提升模块 version,并记录本次变更内容。
更新正式世界的引用文件版本号,备份旧包与旧引用文件。
重启服务端后检查日志中的包加载记录,再让少量玩家确认看到的是新版本。
保留至少一个旧版本包副本,发现问题时可以迅速回退。
七、常见问题
有人问为什么改了贴图玩家看不到。最常见原因是版本号没变,客户端仍使用缓存。
还有人问包放进去完全没反应。检查 UUID 是否与其他包冲突、引用文件是否包含该包、JSON 是否合法。
也有人遇到更新后部分功能消失。通常是依赖包版本不匹配或加载顺序被改变。
最后一个常见问题是回退后仍显示新内容。回退时同样需要调整引用版本,并提醒玩家清理缓存。
执行步骤
- 为每个内容包建立清单,记录 header uuid、模块 uuid、版本与负责人。
- 确认所有 UUID 唯一,复制模板包时立即更换。
- 每次内容变更提升 header version 并记录变更说明。
- 同步更新世界引用文件中的包版本。
- 检查 dependencies 是否齐全且版本匹配。
- 在测试世界验证后再部署到正式世界。
- 重启后检查日志中的包加载记录。
- 保留旧版本包与旧引用文件以便回退。
验收标准
- 服务器上不存在重复的 header 或模块 UUID。
- 世界引用文件中的版本与包实际版本一致。
- 更新后玩家看到的是新版本内容。
- 依赖包齐全且版本匹配。
- 日志中无包加载失败或冲突警告。
- 存在可回退的旧版本包副本。
常见误区
- 复制模板包不换 UUID,导致包被忽略。
- 更新内容不提升版本号,客户端继续用旧缓存。
- 只替换包文件,不更新世界引用版本。
- 手工编辑引用 JSON 出现语法错误,所有包失效。
- 多个资源包互相覆盖同一文件,显示结果不可预期。
- 没有旧版本副本,出问题无法回退。
内容包的稳定迭代靠的是规范的版本管理。身份用 UUID 固定、更新用版本号区分、世界用引用文件对齐,玩家看到的才会始终是你想发布的那一版。