itzg/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
配完之后的终态是这样的：你把一份 compose 文件交给docker compose up -d，服务器自动下载对应版本、进游戏、没人上线时自己休眠，RCON 密码也早就换掉了——你只需要偶尔看一眼docker ps里的 healthy。而真正拦住大多数人的，其实只有几个 itzg/minecraft-server 环境变量。这篇指南按"先跑起来 → 跑得快 → 管得住 → 省心得"四步带你配完，每一步只讲你当下会卡住的东西，不提前剧透。
itzg/minecraft-server 环境变量配置从 docker run 到 docker compose 的迁移示意
最小启动配置：三个变量让服务器跑起来能进游戏
场景：你刚装好 Docker，想让朋友今晚就能连进来。
你会卡在哪：日志里反复滚EULA相关的报错，或者服务器起来了但你从外网怎么都连不上。前者是少了同意协议，后者是忘了把 25565 端口映射出来、数据目录也没挂载。
怎么配：最小启动只需要下面这几项。EULA管你答不答应 Mojang 的用户协议，不设它服务器根本不会启动；TYPE决定跑哪种服务端，不设默认是 VANILLA；VERSION决定玩哪个版本，不设默认 LATEST。
| 变量 | 作用（人话） | 建议值 |
|---|---|---|
EULA | 同意用户协议，不设直接退出 | TRUE |
TYPE | 服务端类型，不设跑原版 | PAPER |
VERSION | 游戏版本，不设追最新，世界升级时容易翻车 | 固定版本号，如1.21 |
MOTD | 服务器列表里显示的那行字，不设显示默认文案 | 随意，如My Server |
必须原样抄的就两行（其余按你机器情况改路径）：
EULA: "TRUE" volumes: - ./data:/data再加ports: ["25565:25565"]对外放端口，把宿主机目录挂到容器/data——世界数据、玩家存档全在这个目录里，不挂载的话删容器等于删世界。
配完什么效果：docker compose up -d之后，首次启动会花几分钟下载服务端，日志出现Done后朋友就能用主机 IP + 25565 进游戏。更完整的启动说明见官方入门文档。
跑起来只是及格线。接下来你会发现人多时掉帧、世界生成时卡顿——那是资源配置的问题。
性能与资源：内存该给多少，JVM 标志要不要开
场景：服务器能玩了，但人一多就卡，你怀疑是内存不够。
你会卡在哪：把MEMORY盲目拉到 8G，结果把宿主机挤爆；或者只设了堆内存，忘了 JVM 堆外还要占内存，容器 OOM 被杀。
怎么配：MEMORY同时设定 JVM 的初始和最大堆内存，默认只有 1G，多人玩肯定不够；INIT_MEMORY和MAX_MEMORY可以把这两个值拆开调，比如"先给 1G 快速启动，最多涨到 4G"。经验值是容器总限制 = 堆内存 + 25% 的余量，因为堆外内存是真实存在的。
| 变量 | 作用（人话） | 建议值 |
|---|---|---|
MEMORY | 初始=最大堆内存一把梭，默认 1G | 按玩家数给，2G起步 |
INIT_MEMORY/MAX_MEMORY | 分别控制起步和上限，省得每次启动都吃满 | 1G/4G |
USE_MEOWICE_FLAGS | 一键套用 MeowIce 的 G1 垃圾回收调优（Java 17+ 版 Aikar 标志），不开就是默认 GC，人多时卡顿明显 | true |
JVM_OPTS/JVM_XX_OPTS | 逃生舱，塞任意 JVM 参数；不懂就别碰 | 留空 |
垃圾回收标志别自己手写-XX:+UseG1GC那一串，USE_MEOWICE_FLAGS=true一个开关就包含了社区验证过的整套调优，比手动拼参数稳。详细取舍可查 JVM 选项文档。
世界生成方面，SEED定世界种子（不设每次开局随机），LEVEL_TYPE定地形类型（如FLAT、amplified），GENERATOR_SETTINGS是给生成器的 JSON 参数（如 superflat 的层配置）。这些是玩法向的，不影响性能，不改也能玩，映射关系见 server.properties 文档。
配完什么效果：多人在线时掉帧频率明显下降，启动速度因INIT_MEMORY小而变快，内存占用有上限不会失控。
卡帧解决了，下一个问题自然浮现：这台服上，谁说了算？
权限与安全：谁来管服务器，管多严
场景：朋友都进来了，你得决定谁能进、谁有权限、你本人怎么远程下发命令。
你会卡在哪：RCON 默认就是开着的，而它的密码是镜像随机生成的——如果你顺手把 25575 端口也映射出去，等于把管理入口的钥匙挂在门上，只是你不知道钥匙长什么样。
怎么配：
| 变量 | 作用（人话） | 建议值 |
|---|---|---|
RCON_PASSWORD | RCON 管理密码，默认是随机值，暴露端口却不改它就等于不设防 | 自己生成的长随机串 |
ENABLE_RCON | 开关 RCON，关掉会失去一些控制台功能，不建议关 | 保持默认true |
RCON_PORT | RCON 监听端口 | 默认 25575，不要映射到公网 |
ENABLE_WHITELIST | 开启白名单模式，不开则所有人可进 | 公网服必开true |
WHITELIST | 逗号分隔的玩家名列表，和上一项配对使用 | alice,bob |
DIFFICULTY | 难度，可选 peaceful/easy/normal/hard，不设默认 easy | 按服规 |
MODE | 默认游戏模式，不设默认生存 | 按服规 |
白名单是公网服的第一道闸：只要WHITELIST有值，白名单就自动生效，没在名单里的人连门都摸不到。完整列表管理（包括从文件导入）见 官方变量表。
配完什么效果：陌生玩家被挡在白名单外，你在本地用 RCON 客户端或 mc-send-to-console 脚本 下发命令，25575 端口始终只对内网可见。
管得住之后，最后一个问题是：没人盯着的夜里，服务器怎么办？
自动化与可观测：没人盯着时它自己怎么干
场景：朋友只晚上在线，白天服务器却一直在吃 4G 内存空转。
你会卡在哪：开了自动暂停，服务器恢复时却被告诉"某个 tick 卡太久"然后强制重启——这是没关 watchdog，暂停在服务器眼里就是一次超长卡顿。
怎么配：
| 变量 | 作用（人话） | 建议值 |
|---|---|---|
ENABLE_AUTOPAUSE | 无人连接后把 Java 进程挂起，有人连再唤醒，客户端无感知 | true |
AUTOPAUSE_TIMEOUT_EST | 最后一名玩家离开后多少秒暂停，默认 3600 | 按作息调，如1800 |
MAX_TICK_TIME | 必须配合改：看门狗超时阈值，不改它会在恢复时杀掉服务器 | -1（彻底关闭） |
ENABLE_AUTOSTOP | 更激进：直接停掉容器而非挂起，省全部资源，与自动暂停互斥 | 按需二选一 |
LOG_TIMESTAMP | 日志行加时间戳，排障时能对上时间线 | true |
注意两件事：一是 1.21.2 及以上版本已有原生空服暂停，直接用PAUSE_WHEN_EMPTY_SECONDS即可，不必再上ENABLE_AUTOPAUSE；二是 Paper 服还要加JVM_DD_OPTS=disable.watchdog:true才关得干净。细节和knockd网络接口的坑都写在 Auto-Pause 文档里。
日志不用额外配置——镜像已默认开启滚动日志，按天归档成logs/*.log.gz，ROLLING_LOG_MAX_FILES控制保留多少份，磁盘不会被写爆。健康检查也是内置的：镜像自带 mc-monitor 持续探测，docker ps的 STATUS 列直接显示healthy，想自定义探测间隔见健康检查文档。
配完什么效果：白天没人玩时进程自动挂起，内存占用掉到接近零；有人一敲门（客户端 ping）就唤醒；你随时docker compose ps一眼确认死活。
常见翻车点与可直接抄的完整清单
先把翻车点过一遍，都是真实高频事故：
- 忘了
EULA：服务器启动几秒就退出，日志里有明确提示 - 没挂
./data:/data：容器一删世界全没，这是最贵的一课 - 端口只映射了 25565 却连不上：先查宿主机防火墙
- 25575 映射到公网且
RCON_PASSWORD是默认随机值：等于开放管理入口，立刻改密码并收回端口 - 开了自动暂停却没关 watchdog：恢复后服务器自我了断
MEMORY设 4G 但容器没有限制：宿主机被挤爆，记住堆外还要加 25%
最后是一份可以直接抄进 compose 的完整环境清单，覆盖前四步：
environment: EULA: "TRUE" TYPE: PAPER VERSION: 1.21 MOTD: "My Server" MEMORY: 2G USE_MEOWICE_FLAGS: "true" RCON_PASSWORD: "换成你自己生成的长随机串" ENABLE_WHITELIST: "true" WHITELIST: "alice,bob" DIFFICULTY: normal ENABLE_AUTOPAUSE: "true" AUTOPAUSE_TIMEOUT_EST: "1800" MAX_TICK_TIME: "-1" LOG_TIMESTAMP: "true"配合前面提到的ports、volumes两段，docker compose up -d就是你的日常。之后想加 mod 包、换 Fabric、接 Geyser，仓库的 examples 目录 里有大量现成 compose 文件可以照着改——每个阶段只加对应的那几个变量即可。
变量表本身会随版本变化，以 官方变量文档 和 types-and-platforms 文档 为准；这份指南解决的是"先配哪几个、为什么"，查细节再回官方文档找对应段落就行。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
