BlueMap 指南：为你的 Minecraft 服务器打造 3D 网页地图

BlueMap 是什么

BlueMap 读取你的世界文件，将其渲染成 3D 地图图块，并通过一个小型内置网页服务器提供访问。放大时可以看到完整 3D 的方块；缩小后则是平面概览。实时标记会显示玩家所在位置，地图也会随着世界的变化而更新。

它只渲染 Java Edition 世界。当前版本 BlueMap 5.29 提供以下版本：

如果使用较旧的 Minecraft 版本，请下载列出该版本的旧版 BlueMap。Modrinth 和 Hangar 上的每个版本都会标明其支持的游戏版本。

安装 BlueMap

1. 从 Modrinth、Hangar 或 BlueMap 的 GitHub releases 下载与你服务器匹配的文件：Paper 用 -paper jar，Fabric 用 -fabric，以此类推。
2. 将其放入 plugins 文件夹（Paper、Spigot）或 mods 文件夹（Fabric、Forge、NeoForge），然后重启服务器。上传插件的方法见如何安装 Minecraft 插件。
3. BlueMap 会在 plugins/BlueMap/（模组服务器则为 config/bluemap/）中生成配置，并已为你的每个世界设置好一张地图。

此时控制台会提示 BlueMap 正在等待。在你接受下载之前，它不会渲染任何内容，这就是下一步。

在 core.conf 中接受下载

为了绘制方块，BlueMap 需要 Minecraft 客户端的材质和模型，它会从 Mojang 下载这些资源。打开 core.conf 并修改：

accept-download: true

设置此项即表示你接受 Mojang 的 EULA，并确认你拥有 Minecraft Java Edition。保存文件后运行 /bluemap reload，或重启服务器。BlueMap 会下载资源并开始渲染。

为网页地图分配独立端口

BlueMap 的网页服务器默认监听 8100 端口。在你自己的机器上，开放该端口并访问 http://your-ip:8100 即可。托管服务器上通常不能随意选择端口，因此需要使用分配给你服务器的端口：

1. 为服务器获取第二个端口。在 HytHost 上，打开面板中的 Network 选项卡并添加一个分配：面板会自动挑选一个空闲端口并为你开放。
2. 打开 webserver.conf，将 port 设为该端口号：

   port: 25570

3. 运行 /bluemap reload，然后在浏览器中打开 http://your-server-ip:25570。

不要使用游戏端口，那是 Minecraft 专用的。若想在自己的域名上显示地图且不带端口号，可以在前面加一个 nginx 之类的反向代理；BlueMap 的文档中有现成的示例。

BlueMap 命令

每条命令都有形如 bluemap.<command> 的权限，例如 bluemap.reload。大多数时候你一条都用不到：BlueMap 会自动发现世界中的变化并进行渲染。

让渲染保持轻量

BlueMap 在后台线程中渲染，而不是在服务器主线程上，但渲染仍然会占用 CPU。大型世界的首次渲染是最吃资源的部分；之后只会重绘发生变化的区块。

• 渲染线程：在 core.conf 中设置 render-thread-count。BlueMap 文档建议在四核及以下的机器上设为 1。
• 在空闲时渲染：首次渲染期间，高峰时段运行 /bluemap stop，夜间再运行 /bluemap start。
• 有玩家在线时暂停：plugin.conf 中的 player-render-limit 会在在线人数达到设定值时停止渲染。
• 设置世界边界。这样地图和渲染工作量就不会随着玩家探索而无限增长。
• 冻结不需要实时更新的地图，例如已经探索完毕的末地。

存储：文件还是数据库

默认情况下，BlueMap 会将地图以压缩文件形式存放在 bluemap/web/maps 中，占用服务器的存储空间。地图会随着已探索区域增大而增长，因此在大型世界上请留意磁盘空间。

你也可以把地图改存到数据库。在 storages/sql.conf 中设置到 MySQL、MariaDB、PostgreSQL 或 SQLite 的连接，然后在该地图的配置文件中设置 storage: "sql" 并重新加载：

connection-url: "jdbc:mysql://DB_HOST:3306/DB_NAME"
connection-properties: {
    user: "DB_USER",
    password: "DB_PASSWORD"
}

Paper 自带 MySQL 驱动；Spigot、Fabric 和 Forge 需要另外添加 JDBC 驱动。每个 HytHost Minecraft 套餐都包含 MySQL 数据库，可在面板的 Databases 选项卡中创建。