docker-minecraft-server 环境变量改配置：4 个部署场景与避坑指南

docker-minecraft-server 环境变量改配置：4 个部署场景与避坑指南

【免费下载链接】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

你有没有过这种经历：Minecraft 服务器要上线了，打开某个插件配置才发现数据库地址被写死在文件里，改完重新打包、重新部署，折腾一晚上。而 docker-minecraft-server 这个镜像恰好提供了对应的解法：启动时读取容器环境变量，把配置文件里的${占位符}替换成真实值，再启动服务器。换句话说，用 docker-minecraft-server 环境变量改配置文件，是它和同类镜像拉开差距的核心能力之一。

先建立心智模型：一条完整的替换链路

这套机制的链路可以压成一句话：

环境变量 → 配置里的${占位符}→ 启动时替换 → 服务器带着最终配置启动。

docker-minecraft-server 的启动脚本会按固定流程走：加载配置、部署对应版本、准备世界、同步插件和模组，然后在最后一步start-finalSetupEnvVariables扫描容器内/data下的文件做变量替换，才真正拉起 java 进程。整个启动链条如下图所示：

记住这个顺序就行：替换发生在开服之前。所以只要占位符写对，服务器第一次启动拿到的就已经是完整配置。

场景一：一份配置，多套环境

要解决什么：开发、测试、生产三套环境，MOTD、数据库地址各不相同，但你不想维护三份配置文件。

怎么配：先把配置里会变的部分改成占位符，挂在/data下：

# database.yml database: host: ${CFG_DB_HOST} name: ${CFG_DB_NAME} motd: ${CFG_SERVER_MOTD}

然后让每个环境的 compose 文件只提供不同的值，文件本体完全复用：

# compose.dev.yml services: minecraft: image: itzg/minecraft-server environment: EULA: "TRUE" CFG_DB_HOST: "db:3306" CFG_SERVER_MOTD: "Dev 服，随便玩"

把两个变量改成测试/生产的值，就是另一份 compose。

效果：同一个database.yml，在不同 compose 下启动会得到不同的最终内容。配置文件进 Git 不带环境差异，环境差异全部收敛到 compose 文件里。

场景二：密钥不要写进 compose 🔒

要解决什么：数据库密码、API 密钥这类信息，真的该以明文写在 compose 文件里吗？

怎么配：把值放进一个文件，通过 secrets 挂载进容器，再用带_FILE后缀的变量指向它——占位符还是原来的名字，变量名加_FILE后缀：

services: minecraft: image: itzg/minecraft-server environment: CFG_DB_PASSWORD_FILE: /run/secrets/db_password secrets: - db_password secrets: db_password: file: ./db_password

配置里照常写${CFG_DB_PASSWORD}，启动时它的值就是db_password文件的全部内容。

效果：密码只在密钥文件里出现一次，不进 Git 历史、不进镜像。换密码只改文件，不用碰任何配置。

场景三：精细控制替换的范围

要解决什么：替换默认会扫过所有匹配的文件，但有些文件（比如插件生成的用户数据）你不希望被动，有些前缀又太宽或太窄。

怎么配：四个开关按需组合：

environment: REPLACE_ENV_VARIABLE_PREFIX: "CFG_" # 只有 CFG_ 开头的变量参与替换 REPLACE_ENV_VARIABLES_EXCLUDES: "userdata.yml" # 按文件名排除 REPLACE_ENV_VARIABLES_EXCLUDE_PATHS: "/data/plugins/Essentials" # 按路径递归排除 REPLACE_ENV_DURING_SYNC: "true" # 同步来的文件也参与替换（默认关闭）

效果：只有${CFG_...}形式的占位符会被替换，${DB_HOST}这类无前缀的保持原样；被排除的文件和目录完全不参与扫描。替换范围从"全有或全无"变成可按需裁剪。

场景四：不止替换——用 JSON 补丁改配置

要解决什么：有些需求不是"填个值"，而是要往已有配置里新增字段、改布尔开关，占位符覆盖不到。

怎么配：写一个补丁集文件（支持 JSON、JSON5、YAML、TOML），通过PATCH_DEFINITIONS指向它。注意file和value里也可以继续用${...}占位符：

{ "patches": [ { "file": "/data/paper.yml", "ops": [ { "$set": { "path": "$.verbose", "value": true } }, { "$set": { "path": "$.settings['velocity-support'].enabled", "value": "${CFG_VELOCITY_ENABLED}", "value-type": "bool" } } ] } ] }

挂载进容器后声明：

environment: PATCH_DEFINITIONS: "/patches/patch-set.json" CFG_VELOCITY_ENABLED: "true"

效果：启动时paper.yml被按补丁逐条修改，值还能由环境变量决定——替换和补丁是两套机制，可以叠着用。

避坑指南：这些错误最容易踩 ⚠️

核心环境变量速查表

想核对更完整的参数说明，看 docs/variables.md；替换和补丁这一节的完整细节在 docs/configuration/interpolating.md。仓库根目录的 examples/ 里有大量可直接抄的 compose 示例，比如 examples/docker-compose.yml 覆盖了最常见的部署写法。

下一步

现在就把某个挂载配置里最"环境相关"的一行改成${CFG_...}，加一个 compose 环境变量，重新docker compose up -d，然后diff一下容器里的文件——看到占位符消失，说明链路已经通了。

【免费下载链接】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