指南 / 服务器与性能

server-icon.png：确切要求，以及没人使用的管理 API

64x64、PNG、位于服务器根目录——三项中任何一项出错，图标都会悄无声息地不显示；隔行扫描和 16 位色深同样会失败，且图标只在启动时读取一次。另外还有取代控制台抓屏的 JSON-RPC 管理 API，应只绑定到 localhost。

2026-06-14

服务器图标是 Minecraft 中最不留情面的小型功能，因为所有失败模式看起来都一样：没有图标，没有报错。

三项要求，全部强制

1. 必须恰好 64×64 像素。 不是 63，不是 128。服务器不会缩放。
2. PNG 格式。 必须是真正的 PNG，不是改了扩展名的 JPG。
3. 命名为 server-icon.png，放在服务器根目录——与 server.properties 并列，而不是放在世界文件夹里。

任何一项出错，服务器都会正常启动并显示默认图标。尺寸错误或文件并非真正的 PNG 会在启动时记录一行日志——Couldn't load server icon——但命名错误或位置错误的文件什么都不会记录。（如果完全没有 server-icon.png，服务器会回退到世界自带的 icon.png，如果有的话。）

其他会导致失败的情况

• 交错 PNG。 有些编辑器默认保存为交错格式；Minecraft 的读取器会拒绝它。请重新导出为非交错格式。
• 16 位色深。 请保存为每通道 8 位。
• 颜色配置文件。 嵌入的 ICC 配置文件偶尔会导致解析器出错。导出时请清除元数据。
• 透明度没问题，在服务器列表中能正确渲染。

服务器只读取一次

服务器在启动时加载 server-icon.png，之后不再读取。在运行中的服务器上替换文件不会产生任何变化，直到重启——这就是为什么在不重启的情况下测试图标更改会让你确信它没生效。重启后，客户端会在下次刷新服务器列表时获取新图标。

管理 API

较新的服务器版本暴露了一个 JSON-RPC 管理接口，这是解析控制台输出或外挂插件的官方替代方案。

在 server.properties 中启用它：

management-server-enabled=true
management-server-host=localhost
management-server-port=25585
management-server-tls-enabled=false

TLS 默认开启，并且需要一个密钥库（management-server-tls-keystore），所以要么指向一个密钥库，要么——仅在 localhost 上——像上面那样关闭它；如果 TLS 开启但没有密钥库，管理服务器不会启动。端口也没有默认值（25585 只是一个例子）。

然后向该端口打开一个 WebSocket，将 server.properties 中的 management-server-secret 作为 Authorization: Bearer <secret> 发送，并使用 JSON-RPC 通信：

{ "jsonrpc": "2.0", "id": 1, "method": "minecraft:players" }

方法涵盖玩家列表、服务器状态、允许列表和封禁列表、游戏规则、设置，以及一对保存/停止方法。每个方法返回结构化 JSON，而不是一行需要你用正则表达式解析的文本。

绑定到 localhost

默认值是 localhost，并且应该保持这样。该接口不面向互联网——任何拿到密钥并访问它的人都能停止你的服务器，而密钥的安全性只取决于你的 server.properties。如果需要远程访问，请通过 SSH 隧道或带身份验证的反向代理来暴露它，绝不要将主机改为 0.0.0.0。

为什么这很重要

仪表盘、Discord 机器人和在线监控历来通过读取控制台日志或使用 RCON 来工作，这两种方式都很脆弱。有了类型化 API，玩家数量小部件就不会因为某行日志改变格式而失效。

将任何图像转换为合规的 server-icon.png，并在服务器图标与 API 工具中浏览 JSON-RPC 方法。

服务器图标与 API 工具 →