squaremap 网页地图插件

squaremap 网页地图插件

> 简约轻量的 Minecraft 服务端实时网页地图，采用原版风格的俯视 2D 渲染，将整个世界实时生成并在任意浏览器中查看；支持 Paper / Folia、Sponge、Fabric、NeoForge 多平台，MIT 开源。
基本信息

| 项目 | 信息 |
| --- | --- |
| 插件名称 | squaremap |
| 开发者 | jpenilla（Owner） |
| 最新版本 | 1.3.13（2025-12，稳定）；1.3.14 已出现于部分镜像（以官方渠道为准） |
| 许可协议 | MIT（squaremap）；前端 Leaflet 采用 2-clause BSD License |
| 兼容版本 | Minecraft Java 1.19.3 – 26.1.2（含 1.21.11、1.21.10、1.21.8、1.21.7、1.21.5、1.21.4、1.21.3 等） |
| 运行平台 | Paper / Folia、Sponge、Fabric（需 Fabric API）、NeoForge |
| 官方网站 | https://squaremap.jpenilla.xyz |
| 官方演示 | https://squaremap-demo.jpenilla.xyz/ |
| 项目地址 | https://modrinth.com/plugin/squaremap |
| 源码仓库 | https://github.com/jpenilla/squaremap |
简介

squaremap 是一款面向 Minecraft 服务端的轻量级实时网页地图插件（亦可作 Mod 运行）。它以插件或模组的形式接入服务端，自动生成并持续维护一张与游戏世界同步的实时地图，玩家与管理人员通过任意现代浏览器即可访问，无需安装任何客户端。

渲染风格沿用 Minecraft 原版地图的视觉语言——简洁的俯视 2D 瓦片图，专为导航设计。相比重量级 3D 地图方案（如需要全分辨率材质的 BlueMap），squaremap 更轻、更快、对服务端性能影响更小，适合希望在"低开销"与"可用性"之间取得平衡的服务端。

squaremap 内置集成 Web 服务器，地图可直接通过端口访问；同时提供简单的 API，允许扩展插件在地图上绘制标记（markers）、图形（shapes）、图标（icons）等，并已与 Towny 等流行插件形成集成。官方还提供了一个可直接体验功能的在线演示实例。
核心特性
极速渲染
渲染速度极快，后台渲染机制可持续增量更新地图，配合多线程渲染（max-render-threads）与分块间隔控制，对在线玩家几乎无感知。
原版风格 2D 视图
采用与原版地图一致的俯视 2D 瓦片风格，画面简洁、辨识度高，专为实际导航而非观赏性设计；支持生物群系着色（biomes / blend-biomes）、玻璃透明、岩浆棋盘格、水体透明深度等视觉选项。
玩家标记
地图上实时显示在线玩家标记，包含朝向（yaw 旋转）、生命值、护甲值，并可通过名字牌（nameplate）配置；玩家使用披风/装备标签 MAP_INVISIBILITY_EQUIPMENT 时可自动隐藏。
多平台统一
同一套核心覆盖 Paper / Folia、Sponge、Fabric、NeoForge 四大平台，每平台有独立 jar；Paper 分支特别针对 Folia 的多线程模型做了同步处理。
内置 Web 前端
基于 Leaflet（并保持最新），开箱即用；支持坐标显示、链接按钮、可固定侧边栏、世界列表、缩放层级（zoom）等 UI 控制；前端已迁移至 Vite 工程化构建。
简单 API
提供绘制标记、图形、图标的简单 API；Javadoc 随二进制文件发布在 Maven 仓库中，IDE 会自动下载。社区扩展涵盖 Towny 区域、阵营领地、自定义标记等。
灵活部署
内置 HTTP 服务器可绑定指定端口与地址；同时支持将 web/ 目录交给 Nginx 等外部 Web 服务器托管（适合大型网络），支持 static 模式减少非变动地图的 Web 请求。
环境要求

| 项目 | 要求 |
| --- | --- |
| 服务端 | Paper / Folia（推荐）、Spigot 分支；或通过 Sponge / Fabric / NeoForge 加载 |
| Minecraft | Java 版 1.19.3 – 26.1.2 |
| 前置依赖 | Fabric 平台需 Fabric API；NeoForge 平台需对应加载器 |
| 端口 | 默认 8080（内置 Web 服务器），需在防火墙 / 面板开放对应端口 |
| 头像接口 | 默认 https://mc-heads.net/avatar/{uuid}/16，可替换为自建或 SkinsRestorer 地址 |
近期更新

| 版本 | 日期 | 主要变更 |
| --- | --- | --- |
| 1.3.13 | 2025-12 | SNAPSHOT 主线，1.21.11 适配、Fabric 权限 API 更新、前端依赖升级 |
| 1.3.12 | 2025-12-12 | 修复 Fabric / NeoForge 上发送命令报错（#501） |
| 1.3.11 | 2025-12-11 | 修复 Fabric 加入世界报错（#500） |
| 1.3.10 | 2025-12-10 | 适配 Minecraft 1.21.11 |
| 1.3.9 | 2025-10-10 | 适配 Minecraft 1.21.10；更新 pt-br 语言（#406） |
| 1.3.8 | 2025-07-19 | 适配 1.21.8；修复 UILink 初始化顺序（#441） |
| 1.3.7 / 1.3.6 | 2025 | 适配 1.21.7（#422、#430） |
| 1.3.5 | 2025-04-28 | 新增 /map link 命令；static 选项；前端转 Vite 工程；修复正北朝向旋转、移动端侧边栏、标记闪烁、名字牌对齐等 Web 问题 |

> 注：1.3.13 之后已有 1.3.14 镜像记录，且主线曾合入 26.1.2 适配与 framed blocks 修复（#514）。因 Modrinth 页面仅标注"Published 3 years ago"、未列精确版本号与逐条 Changelog，上表以 GitHub Releases、官方论坛公告及镜像渠道交叉印证，请以项目页 / GitHub Releases 实际发布为准。
相关链接
Modrinth 下载：https://modrinth.com/plugin/squaremap
Hangar（Paper 版）：https://hangar.papermc.io/jmp/squaremap
GitHub Releases：https://github.com/jpenilla/squaremap/releases
官方文档 / Wiki：https://github.com/jpenilla/squaremap/wiki
命令与权限 Wiki：https://github.com/jpenilla/squaremap/wiki/Commands-and-Permissions
官方演示：https://squaremap-demo.jpenilla.xyz/
扩展 / 集成列表：https://github.com/jpenilla/squaremap#addons-and-integrations