📖bedrock-protocol-docs是 Minecraft: Bedrock Edition 官方发布的网络协议文档仓库，收录了超过 500 个网络数据包（packet）的完整 JSON Schema 结构。无论你是想开发第三方服务器、写协议工具，还是单纯好奇"客户端和服务端到底在互相发什么"，都能通过 LoginPacket、DisconnectPacket 等核心包的定义，快速看懂 Bedrock 网络协议的运作方式。

本文将带你用5 个步骤，从仓库结构、单个数据包解析、字段约定到连接生命周期，系统地读懂这 500+ 个数据包结构。

1️⃣ 先认识仓库：500+ 数据包都在哪里？

打开 README.md 可以看到仓库分为 4 个核心区域：

📌 关键认知：json/目录下每个.json文件就是一个类型或数据包的定义，其中239 个以*Packet.json命名的文件对应当前协议版本（x-protocol-version: 2225，对应 Minecraft 1.26.60-beta）的顶层数据包。它们加上 Payload、枚举等辅助定义，共同构成了"500+ 网络数据包结构"的完整图谱。

2️⃣ 读懂一个数据包：以 LoginPacket 为例

每个数据包都由两个文件组成，这是读懂全部 500+ 包的万能钥匙：

• XxxPacket.json：包的"身份证"——名称、说明、协议 ID
• XxxPacketPayload.json：包的"身体"——具体字段和类型

以 json/LoginPacket.json 为例：

{ "title": "LoginPacket", "x-minecraft-version": "1.26.60-beta.0", "x-protocol-version": 2225, "description": "Sent once from client to server at login. About 100k.", "$ref": "./LoginPacketPayload.json", "$metaProperties": { "[cereal:packet]": 1 } }

逐字段拆解（这个模式适用于所有包）：

再顺着$ref打开 json/LoginPacketPayload.json，就能看到实际传输的字段：

💡 小技巧：字段上的x-ordinal-index表示序列化顺序，x-underlying-type表示底层类型，x-serialization-options标注字节序/压缩等序列化规则——看字段时优先扫这三个属性，就能推断出线格式。

3️⃣ 从 Login 到 Disconnect：一次连接的完整生命周期

把数据包按"连接阶段"串起来读，比一个个硬啃高效得多。下面是一次典型连接中你最先遇到的几个包（ID 来自各json文件中的[cereal:packet]）：

连接结束时的 json/DisconnectPacketPayload.json 是个很好的进阶范例，演示了协议中的联合类型写法：

• Reason：引用枚举 json/DisconnectFailReason.json，告诉客户端为什么被踢；
• Messages：使用oneOf表示"要么是消息体、要么为null"，并通过x-control-value-type: uint32声明判别值——看懂这一处，oneOf+ 判别值这个在 500+ 包里反复出现的模式就全通了。

🕹️ 想深入"服务端如何判定与纠正玩家"？推荐对照阅读 additional_docs/PlayerMovementOverview.md 和 additional_docs/ConfiguringAntiCheat.md，它们解释了MovePlayerPacket背后的 rewind 反作弊机制。

4️⃣ 高效查找技巧：在 500+ 包里快速定位

关键词搜索三件套

在仓库根目录用grep按关键词搜包名和用途，是最快的定位方式：

# 按用途关键词找包（在 description 里搜） grep -l "block breaking" json/*.json # 找所有数据包主文件（排除 Payload/枚举） ls json/*Packet.json

按命名规律分类记忆

• *Packet.json/*PacketPayload.json：数据包本体与字段
• Clientbound*/Serverbound*：显式标注方向的包
• *_Action/__Type类文件：包内的枚举与子操作（如拆方块动作类型）

配套文档一起看

• 指南入口 additional_docs/README.md：解释了 guides 导航的组织方式（首层目录=分区，首级标题=标题）
• 拆方块机制：additional_docs/BlockBreakingOverview.md
• 各版本开发者笔记：developer_notes/r26u5/、developer_notes/r21u6/ 等，共 13 个版本目录
• 历史变更记录：legacy_changelogs/，协议"逐版本会变"（subject to change），查改动看这里

5️⃣ 常见问题（FAQ）

Q1：协议会一直变吗？我该看哪个版本？会。仓库明确说明协议随版本变化。当前json/对应协议版本 2225（Minecraft 1.26.60-beta），历史版本可通过 legacy_changelogs/ 与 developer_notes/ 追溯。

Q2：只想本地运行文档网站？按 README.md 说明，使用 Node.js 24+ 后执行：

npm ci npm run dev

Q3：x-format-version显示 "MISSING VERSION" 是什么？这是生成阶段尚未填充的占位值，不影响字段定义阅读；真正可用的版本信息在x-protocol-version字段中。

总结：一份快速上手清单 ✅

1. 定位：数据包主文件在 json/，命名规律XxxPacket.json+XxxPacketPayload.json
2. 看身份证：description讲用途，[cereal:packet]是包 ID
3. 看字段：跟着$ref进 Payload，重点关注x-underlying-type、x-ordinal-index、oneOf判别值
4. 串流程：LoginPacket → PlayStatusPacket → （游戏数据）→ DisconnectPacket，按阶段记忆
5. 查细节：机制类问题去 additional_docs/，版本演进去 legacy_changelogs/

掌握这套方法，500+ 个网络数据包对你来说就不再是陌生的 JSON 堆，而是一张可以按图索骥的地图 🗺️