MCXboxBroadcast是一个专为 Geyser / Bedrock 服务器打造的 Geyser 扩展：它把你的服务器"广播"到 Xbox Live，让已登录 Microsoft 账号的好友在游戏内的"好友"列表中直接看到一个可加入的 Minecraft 会话。本文带你完成从下载 jar 到 Xbox 游戏内显示服务器的 7 步完整流程，零基础也能一次装好。

一、MCXboxBroadcast 能为你做什么？

在动手安装前，先了解这个 Geyser 扩展的核心能力（详见 README.md）：

⚠️风险提示：该工具会模拟部分客户端行为，理论上可能与 Xbox 服务条款冲突。官方建议使用备用（小号）账号运行，账号风险请自行承担。

二、7 步安装流程（Geyser 扩展版）

整个安装过程不需要写代码，跟着下面 7 步走即可。

步骤 1：下载最新的扩展 jar 包

从项目的 Release 页面下载最新版本文件MCXboxBroadcastExtension.jar（扩展版，注意不要下成 Standalone 版）。该扩展通过 extension.yml 声明为 Geyser 扩展，要求 Geyser API2.12.1及以上版本，请确认你的 Geyser 版本满足要求。

步骤 2：把 jar 放入 Geyser 的 extensions 目录

将下载好的MCXboxBroadcastExtension.jar直接拖入你的 Geyser 服务器根目录下的extensions文件夹即可：

Geyser 根目录/ ├── extensions/ │ └── MCXboxBroadcastExtension.jar ← 放这里 ├── config.yml └── ...

扩展启动逻辑见 MCXboxBroadcastExtension.java，它会在 Geyser 初始化完成后自动加载config.yml并创建数据目录。

步骤 3：重启 Geyser 服务器，等待认证代码

重启服务器后，等待扩展启动。控制台会打印一条类似这样的认证提示：

To sign in, use a web browser to open the page https://www.microsoft.com/link and enter the code XXXXXXXX to authenticate.

记下这串 8 位认证代码，这是下一步登录的关键。

步骤 4：浏览器完成 Microsoft 账号登录

在任意浏览器中打开提示里的微软登录链接，输入上一步的认证代码，然后登录你想用来广播的 Microsoft 账号（再次建议用小号）。登录成功后，控制台会收到回调，扩展自动建立与 Xbox Live 的会话连接（由 SessionManager.java 负责创建和定时刷新会话）。

步骤 5：在 Xbox Live 上把广播账号加为好友

这一步最容易被忽略：广播会话只会推送给"好友的好友"，所以你（以及想看到服务器的玩家）必须先在 Xbox Live 上把这个账号添加为好友。添加后，工具默认会自动接受好友请求并发送初始邀请（见 FriendManager.java 的autoFriend/initialInvite配置）。

步骤 6：进入游戏"好友"标签页确认服务器

打开 Minecraft（Bedrock 版），进入好友（Friends）标签页，你应该能看到广播的服务器会话了，点击即可加入游戏 🎉。同时该账号会在 Xbox 应用与网页端显示"在线并正在游玩 Minecraft"。

步骤 7（可选）：进阶配置与美化

基础流程走通后，可以做这些锦上添花的配置：

• 自定义封面图：在config.yml同目录放一张名为screenshot.jpg的图片，推荐尺寸1200x675、质量90、色度采样4:2:0（图片上传逻辑见 GalleryManager.java）。
• 常用参数调整：updateInterval刷新间隔（受 Xbox 限流限制，最小 20 秒）、hideOldSessions会话满员后的行为等，完整字段定义见 CoreConfig.java。
• Docker 部署独立版：如果你不想依赖 Geyser，可用官方镜像运行 Standalone 版（见 Dockerfile）：

docker run --rm -it -v /path/to/config:/opt/app/config ghcr.io/mcxboxbroadcast/standalone:latest

启动独立版后，记得在config.yml中把remoteAddress/remotePort改成你的目标服务器地址（auto默认指向127.0.0.1:19132，见 StandaloneMain.java），再重启工具即可。

三、实用命令速查表

扩展版在 Geyser 控制台执行命令时需加前缀/mcxboxbroadcast：

四、常见问题排查

• 游戏内看不到服务器：先确认是否已完成步骤 5（把广播账号加为 Xbox Live 好友）；再确认账号是 Bedrock 版客户端。
• 提示"Xbox Session expired"：会话认证过期，用restart命令或重启 Geyser 重新走一次代码登录流程；也可配置 Slack/Discord Webhook 通知，收到提醒及时处理（见 CoreConfig.java 中的notifications段）。
• 刷新间隔报错：updateInterval最小只能设为 20 秒，低于该值会被 Xbox 限流拒绝。
• 面板一键部署：使用 Pterodactyl Panel 的用户可直接导入官方 egg 文件 egg-m-c-xbox-broadcast.json 快速创建实例。

按照以上 7 步，你的服务器就已经成功出现在 Xbox Live 的好友列表中了。祝联机愉快！🚀