一个镜像部署 Minecraft 服务端：docker-minecraft-server 启动与调参指南-开发者社区

一个镜像部署 Minecraft 服务端：docker-minecraft-server 启动与调参指南

【免费下载链接】docker-minecraft-serverDocker image that provides a Minecraft Server for Java Edition that automatically installs/upgrades versions, modloaders, modpacks and more at startup项目地址: https://gitcode.com/GitHub_Trending/do/docker-minecraft-server

itzg/minecraft-server 是一个 Minecraft Java 版服务端的 Docker 镜像，核心能力是：启动时自动下载指定版本的服务器文件，并可按配置自动装好模组加载器与整合包。它适合想在自己机器或服务器上长期运行原版服、插件服或整合包服的玩家。你只需要一份十来行的 Compose 文件，就能先跑起来一个可联机、可持久化的服务端。

先判断它适不适合你

适合的场景：

你想长期运行一个 Java 版 Minecraft 服务端，且希望版本升级、模组下载这些琐事交给容器启动流程处理。
你要在原版、Paper、Forge、Fabric 等多种服务端形态之间切换，只改环境变量而不是换一套部署方案。
你需要挂载卷来备份世界、换宿主机迁移，或者用 Compose / Kubernetes 做增量配置。

不太适合的场景：

你要运行基岩版（Bedrock）服务端。该镜像只支持 Java 版，基岩版需要使用另一个专门的镜像（项目文档 examples 中有通过 Geyser 桥接基岩玩家的示例）。
你只想要一个单机小游戏客户端，而不是对多人联机服务端做运维。

最短路径跑起来

推荐用 Docker Compose 而不是裸docker run，这样以后改配置、换镜像都只需重跑一条命令。在任意目录创建compose.yaml：

services: mc: image: itzg/minecraft-server:latest tty: true stdin_open: true ports: - "25565:25565" environment: EULA: "TRUE" volumes: - ./data:/data

然后执行docker compose up -d，用docker compose logs -f看启动日志，客户端指向本机 IP 的 25565 端口即可。三个关键变量：

EULA=TRUE：Mojang 要求必须接受 EULA 协议才会启动，漏掉它容器会直接报错退出。
./data:/data：把宿主机目录挂到容器内的/data，世界和配置都存在这里。不挂的话 Docker 会建一个匿名卷，删容器时数据一起消失。
tty/stdin_open：让容器保留一个可用的控制台会话，部分服务端类型需要它来模拟终端输入。

如果你只想快速验证一下环境，也可以先跑一次性命令：

docker run -d -it -p 25565:25565 -e EULA=TRUE -v /home/user/minecraft-data:/data itzg/minecraft-server

Docker run 到 Compose 的迁移示意

选择部署形态

服务端类型通过TYPE环境变量选择，同一个镜像覆盖从纯净到重度模组的全部形态。按需求分三类来看：

追求稳定和性能：TYPE=PAPER（Paper 是 Minecraft 服务端的一种性能优化分支）、SPIGOT、MAGMA、FOLIA等。这类适合带插件的多人服，也是大多数生产部署的选择。
需要装模组：TYPE=FORGE、FABRIC、NEOFORGE、QUILT、MOHIST等。这类要额外指定加载器自身的版本号，见 docs/types-and-platforms/。
不想关心加载器：直接用整合包平台模式（下一节讲），由镜像根据整合包声明自动选 Forge/Fabric 并装好全部模组。

每种类型下，VERSION变量统一表示 Minecraft 游戏本身的版本，各类型另有自己的加载器版本变量（如 Forge 版本、Fabric 版本）。更多形态说明见 docs/types-and-platforms/server-types/。

自动化能力说明

镜像在启动阶段会自动完成三件事：下载指定版本的服务器 jar、按配置下载并校验模组/插件/数据包、清理旧版本残留。你主要配置的是"装什么"，而不是"怎么装"。

按使用方式分两层：

整合包平台：设置MODPACK_PLATFORM（为兼容旧配置也可写在TYPE里）指向 CurseForge、Modrinth、PackWiz、Spigot 等来源，再给一个项目 ID 或页面地址，启动时镜像会解析该整合包声明的加载器版本、下载所有模组并解压附加文件。仓库里 examples/auto-curseforge/ 下有 ATM8、FTB、Pixelmon 等一批现成 Compose 示例可直接参考，例如 ATM8 的核心配置：

environment: EULA: "true" MODPACK_PLATFORM: AUTO_CURSEFORGE CF_PROJECT_ID: "325345" MEMORY: "4G"

手动指定：不想走整合包时，可以用MODS、MODS_FILE等变量传 URL 或容器内文件列表单独装模组；数据包用DATAPACKS，VanillaTweaks 用分享码VANILLATWEAKS_SHARECODE。新包下载后旧版本会被自动清理。

各平台支持的变量与排除规则细节，见 docs/mods-and-plugins/。

版本与运行环境

这里有两组版本要分开理解：Minecraft 游戏版本和 Java 运行时版本。

游戏版本由VERSION控制，取值为LATEST（默认）、SNAPSHOT、具体版本号（如1.20.4、1.7.9）或新编号体系的26.1等。设为LATEST或SNAPSHOT时，重启容器就会自动检查并升级到最新可用版本，升级后旧 jar 留在/data里可以安全删除。

Java 版本由镜像 tag 决定，latest会跟随 Mojang 对最新版 Minecraft 的 Java 要求。常见对应关系：

游戏版本范围	建议镜像 tag	选择要点
最新版（含 1.20+）	`latest`或`java25`	默认 tag，Java 版本随新版游戏自动跟随
1.18 ~ 1.21	`java17`或`java21`	部分模组仍只兼容 Java 17，遇到 Mixin 报错时优先换它
1.17 及以下	`java8`	Forge 1.18 之前的版本必须使用 Java 8

完整 tag 列表（含 alpine、GraalVM、arm64 架构变体）见 docs/versions/java.md。另外建议给 JVM 加内存控制：MEMORY=4G同时设初始与最大堆，INIT_MEMORY/MAX_MEMORY可分开设置，USE_AIKAR_FLAGS=true可开启针对 Minecraft 调优过的 GC 参数，详见 docs/configuration/jvm-options.md。

数据与持久化

一切与服务器相关的文件都在容器内/data下：世界在/data/<世界名>（由LEVEL变量决定目录名），配置文件是/data/server.properties，模组在/data/mods。日常要记住的就是一件事：把/data挂到宿主机目录或命名卷。

几个实用能力：

备份与迁移：停服后直接拷贝/data对应目录即可；换机器后挂回去就能继续。
从存档包导入：设置WORLD指向一个 zip/tar 压缩世界存档的 URL 或容器内路径，镜像会找到level.dat并把所在子目录解到世界目录，适合直接导入从网上下载的存档。
从已有世界克隆多份：把源世界目录以只读方式挂载（-v ~/worlds:/worlds:ro），再设WORLD=/worlds/basic，即可复制出一个干净的新世界；FORCE_WORLD_COPY=TRUE可让每次启动都强制覆盖。
在 rootless / Podman / SELinux 环境运行时，给卷映射加:Z后缀（如./data:/data:Z）避免权限问题。

完整的目录结构与卷转换方法见 docs/data-directory.md。

排障清单

按"现象 → 可能原因 → 处理办法"排查：

启动日志出现class file version 65.0的UnsupportedClassVersionError：镜像里的 Java 太旧，拉取最新latest镜像或显式改用java21tag。
Forge 启动报ClassCastException ... AppClassLoader cannot be cast to URLClassLoader：这是 Java 8 时代的典型报错，说明该 Forge 版本需要java8镜像。
日志卡在 "Changing ownership of /data" 或相关报错：可临时设SKIP_CHOWN_DATA=true跳过该步骤。
下载模组或整合包时出现网络异常：设DEBUG=true打开启动阶段全量日志；涉及下载客户端的网络问题再开FETCH_WIRETAP=true和HELPER_LOGGING_LEVEL=trace查看抓包级日志。
内存不足或 JVM 内存分配报错：先确认MEMORY是否符合预期，并设DEBUG_MEMORY=true看镜像如何计算堆大小；注意容器整体内存限制要大于堆（一般再多留 25%）。
玩家连不上：先用docker compose ps确认容器在运行，再用docker compose logs -f看是否还在初始化；端口冲突时把宿主机侧改为空闲端口，如"25566:25565"。
数据莫名丢失：大概率是启动时没挂/data，产生了匿名卷。可用docker inspect查看挂载来源，再按 docs 中的方法把内容迁移到命名卷。