docker-minecraft-server 环境变量配置实战：3 个阶段搞定动态配置文件

docker-minecraft-server 环境变量配置实战：3 个阶段搞定动态配置文件

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

docker-minecraft-server 会在容器里自动下载并启动指定版本的 Minecraft 服务器；配合 docker-minecraft-server 环境变量，你还能在启动时动态修改配置文件，比如填值、注入密钥、用 JSON Patch 精准改单个字段。本文分 3 个阶段带你上手。

场景：不想把密码写进镜像里

假设你在跑一个 Paper 服务器，插件配置里需要数据库地址，server.properties 里要填 RCON 密码。如果把这些值直接写死在配置文件里，问题有两个：密码会跟着文件提交进 Git；换一套测试环境时，你得把每个文件重新改一遍再重新构建。

那如果在文件里只写"占位符"，真正的值在启动时才通过环境变量注入进来呢？这正是 docker-minecraft-server 动态修改配置文件机制要解决的问题。

核心机制：启动时给模板占位符填值

当REPLACE_ENV_IN_PLACE为true（默认值）时，启动脚本会扫描容器/data下受支持的配置文件，把形如${变量名}的变量替换成容器环境变量里对应的值。你可以把它理解成填空：配置文件是试卷，环境变量是答案表，启动脚本负责把答案填进空里。

为了防止脚本乱抓无关变量，它带了一个白名单：REPLACE_ENV_VARIABLE_PREFIX默认是CFG_，也就是说只有${CFG_...}开头的占位符才会被填上值；把它设为空字符串，则允许匹配任意变量名。

机制讲清楚之后，下面用 compose 文件把它跑起来。

阶段一 · 跑通：5 分钟完成第一个变量替换

先准备一份会放进/data的配置文件（比如某个插件的配置），在里面留两个占位符，写法跟常见脚本语言的${}一样：

server: name: ${CFG_SERVER_NAME} message: ${CFG_MOTD}

下面是能跑通的最小 compose 文件：只起一个服务、映射游戏端口，并用两个CFG_前缀的变量给上面的占位符提供答案；REPLACE_ENV_IN_PLACE默认开启，所以不用显式写它。

services: minecraft: image: itzg/minecraft-server ports: ["25565:25565"] volumes: - mc:/data environment: EULA: "TRUE" CFG_SERVER_NAME: "我的家庭服" CFG_MOTD: "欢迎回家" volumes: mc:

启动前把配置文件放进/data（用卷挂载即可）。容器启动后，脚本会把两个值写进对应占位符。熟悉这个套路之后，下一步要处理的是敏感信息。

阶段二 · 管好：密钥走文件、排除文件、同步时替换

用_FILE后缀从文件读值。不想让 RCON 密码以明文出现在 compose 文件里，可以把密码存成本地文件挂载为 secret。注意环境变量名加_FILE后缀，而配置文件里的占位符照旧写不带后缀的名字：

services: minecraft: environment: CFG_RCON_PASSWORD_FILE: /run/secrets/rcon secrets: rcon: file: ./rcon_password

启动时脚本读取/run/secrets/rcon的内容作为CFG_RCON_PASSWORD的值参与替换，密码自始至终不落在 compose 文件里。

排除不该被替换的文件。替换是批量扫描，如果某个文件内容里恰好有${...}但你不想动它，可以用REPLACE_ENV_VARIABLES_EXCLUDES按文件名排除（不带路径），或用REPLACE_ENV_VARIABLES_EXCLUDE_PATHS递归排除整个目录：

environment: REPLACE_ENV_VARIABLES_EXCLUDES: "userdata.yml" REPLACE_ENV_VARIABLES_EXCLUDE_PATHS: "/data/plugins/Essentials/userdata"

比如玩家数据文件里常有长字符串，排除掉可以避免被误改。

从同步目录进来的配置也想替换怎么办？默认替换只作用于/data下的文件；如果你的配置来自/plugins、/mods、/config这些同步目录，把REPLACE_ENV_DURING_SYNC设为true，同步过来的文件也会按同样规则替换一遍。

替换范围可控之后，剩下的诉求是精准改某个字段，这就到了阶段三。

阶段三 · 精控：用 JSON Patch 精准改一个配置字段

变量替换只负责"你留了占位符"的地方。如果某个字段在配置里根本不存在，或者你想直接新增一项设置，可以用PATCH_DEFINITIONS：把它指向一个补丁定义文件（目录或单个 patch-set 文件），启动脚本会按 JSON 路径对目标文件执行操作。补丁里的file和value字段支持${...}占位符，前缀白名单同样生效。

举例：开启 Paper 的 velocity 支持并打开详细日志。

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

compose 里只需多给两个变量，一个指向补丁文件，一个提供占位符的值。

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

补丁支持 JSON、YAML、TOML 等格式，既能改已有字段，也能新增字段。到这里，配置文件已经可以"编程化"了；动手前先看几条常见坑。

避坑清单：4 个常见问题 ⚠️

1. 前缀不匹配，替换不生效。如果发现${DB_HOST}没被替换，先检查：默认前缀是CFG_，占位符必须写成${CFG_DB_HOST}才能匹配上。
2. 忘了 EULA，容器直接退出。EULA必须设为TRUE才能同意 Minecraft 服务条款，否则容器会在启动时退出，日志里会有明显提示。
3. 别依赖 RCON 默认密码。RCON_PASSWORD默认是启动时随机生成的，文档明确要求你自己修改——要么在环境变量里显式设置，要么用_FILE机制，否则你根本不知道密码是什么。
4. 文件扩展名不在默认清单里。默认替换覆盖.yml、.yaml、.txt、.cfg、.conf、.properties等常见配置扩展名（也包含 json、toml 等），.ini这类文件不在范围内，可以用REPLACE_ENV_SUFFIXES扩充。

另外记住：替换发生在容器启动时，改了环境变量的值要重启容器才会重新生效。

结尾

从占位符填值，到密钥注入、排除规则，再到 JSON Patch 精准改字段，这套环境变量能力让 docker-minecraft-server 的配置文件从"死文件"变成了"启动时填值的模板"。完整的变量清单见 docs/variables.md，更多真实场景可以参考 examples/docker-compose.yml。

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