docker-minecraft-server 构建期打包插件利用 paper-build-plugins 的 /plugins 目录固化 Bukkit/Spigot/Paper 插件【免费下载链接】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导读本文围绕examples/paper/paper-build-plugins/plugins/README.md讲解的插件打包机制展开在基于itzg/minecraft-server定制镜像时将 Bukkit/Spigot/Paper 插件 jar 预置进镜像内的/plugins目录容器启动时这些插件会被自动同步到数据目录/data/plugins。读完本文你将掌握构建期固化插件、运行期自动装载的完整做法理解其背后的start-setupMounts同步链路与相关环境变量并能把这一模式与运行时挂载/plugins卷的方案做合理取舍。机制总览构建期 COPY启动期同步examples/paper/paper-build-plugins/plugins/README.md描述的工作方式只有两个阶段但正是这两个阶段构成了整个插件打包模式的核心构建期image build将下载好的 Bukkit/Spigot 插件 jar如 WorldEdit 等来源于 dev.bukkit.org 等渠道放入plugins/目录Dockerfile 中的COPY指令会在构建镜像时把这些 jar 放置到镜像内的/plugins运行期container startup容器启动时/plugins的内容会被同步进/data/plugins供 Bukkit/Spigot/Paper 等使用插件的服务器类型加载。这一模式最大的价值在于插件作为镜像不可变层的一部分被固化任何人拉取该镜像即可得到一个开箱即用、插件齐全的服务器不需要在运行时额外挂载插件目录或逐个下载。底层实现从 Dockerfile 到同步脚本的调用链虽然镜像构建时的COPY只是 Docker 标准行为但启动时同步到/data/plugins这一步完全由本仓库的启动脚本驱动可以沿源码验证整个链路。镜像中的脚本入口Dockerfile 中通过如下指令把启动脚本拷贝进镜像COPY --chmod755 scripts/start* /image/scripts/随后ENTRYPOINT [ /image/scripts/start ]Dockerfile在容器启动时依次执行start-setupMounts等阶段。同步的核心start-setupMountsscripts/start-setupMounts 是插件以及 mods、config同步的实际执行者: ${COPY_PLUGINS_SRC:/plugins} : ${COPY_PLUGINS_DEST:${PLUGINS_OUT_DIR}} if usesPlugins; then mkdir -p ${COPY_PLUGINS_DEST} log Copying any plugins from ${COPY_PLUGINS_SRC} to ${COPY_PLUGINS_DEST} mc-image-helper-mounts ${COPY_PLUGINS_SRC} ${COPY_PLUGINS_DEST} fi其中PLUGINS_OUT_DIR默认值为/data/pluginsstart-setupMounts因此默认情况下源目录/plugins的内容会被同步到目标目录/data/plugins。同步动作委托给mc-image-helper完成function mc-image-helper-mounts(){ mc-image-helper \ ${subcommand} $updateArg \ --replace-env-file-suffixes${REPLACE_ENV_SUFFIXES} \ --replace-env-excludes${REPLACE_ENV_VARIABLES_EXCLUDES} \ --replace-env-exclude-paths${REPLACE_ENV_VARIABLES_EXCLUDE_PATHS} \ --replace-env-prefix${REPLACE_ENV_VARIABLE_PREFIX} $ }mc-image-helper是 itzg/mc-image-helper 提供的镜像辅助工具由 Dockerfile 在构建时下载并软链到/usr/bin。默认使用sync-and-interpolate子命令即在同步文件的同时执行环境变量插值见后文同步时的环境变量插值小节。什么条件下才会同步插件usesPlugins 判定不是所有服务器类型都会同步/plugins。scripts/start-utils 中的usesPlugins()决定逻辑为function usesPlugins() { if isTrue ${USES_PLUGINS:-}; then return 0 else case $FAMILY in SPIGOT | HYBRID) return 0 ;; esac return 1 fi }也就是说满足以下任一条件时插件目录才会被同步服务器家族FAMILY为 SPIGOT 或 HYBRIDBukkit/Spigot/Paper 及其衍生如 Purpur、Pufferfish、Folia 均属此类显式设置USES_PLUGINStrue——这尤其适用于 Forge/Fabric 等纯 mod 加载器配合混合型插件如 Cardboard的场景。从源码结构可以推断FAMILY在更早的start-setupEnvVariables阶段根据TYPE如PAPER计算得出因此TYPE: PAPER即天然满足 SPIGOT 家族条件。实战构建一个内置插件的 Paper 镜像第一步准备插件 jar参照原文档把需要预置的插件 jar 放入examples/paper/paper-build-plugins/plugins/目录。例如plugins/ ├── WorldEdit-bukkit-7.3.0.jar ├── EssentialsX-2.20.1.jar └── LuckPerms-Bukkit-5.4.133.jar插件来源不限于 WorldEdit任何兼容 Bukkit/Spigot/Paper 的插件EssentialsX、LuckPerms、Vault 等都可以但请务必保证 jar 与你要运行的TYPE此处为PAPER和 MinecraftVERSION兼容。第二步编写定制 Dockerfile在原文档描述的COPY步骤基础上一份最小可用的 Dockerfile 如下FROM itzg/minecraft-server # 将插件 jar 拷贝到镜像内的 /plugins COPY plugins/ /plugins/如果同时需要预置 mods 或配置文件可参照同族机制一并打包FROM itzg/minecraft-server COPY plugins/ /plugins/ # 启动时同步到 /data/plugins COPY mods/ /mods/ # 启动时同步到 /data/mods COPY config/ /config/ # 启动时同步到 /data/config构建docker build -t my-mc-server:with-plugins .第三步运行沿用 examples/paper/compose.yml 的 Paper 部署模板仅替换镜像名services: mc: image: my-mc-server:with-plugins tty: true stdin_open: true environment: EULA: true TYPE: PAPER MEMORY: 2G ports: - 25565:25565 volumes: - mc-data:/data restart: unless-stopped volumes: mc-data: {}启动后可在容器的/data/plugins中确认插件已被同步进入游戏后使用对应插件命令即可验证其已加载。相关环境变量详解原文档虽未展开但start-setupMounts与docs/mods-and-plugins/index.md揭示了这套同步机制可调的全部旋钮实践中按需使用源与目标目录变量默认值说明COPY_PLUGINS_SRC/plugins插件源目录可改为逗号或换行分隔的多个目录见下文多源目录COPY_PLUGINS_DEST/data/plugins即PLUGINS_OUT_DIR插件同步目标目录例如将源目录改为/extra-pluginsenvironment: EULA: true TYPE: PAPER COPY_PLUGINS_SRC: /extra-plugins volumes: - ./plugins:/extra-plugins:ro强制使用插件USES_PLUGINS如前所述USES_PLUGINStrue可以强制启用/plugins同步典型用途是 Forge/Fabric 加载器配合 Cardboard 等插件兼容层。docs/mods-and-plugins/index.md给出的示例environment: EULA: TRUE TYPE: FABRIC MODRINTH_PROJECTS: | fabric-api cardboard USES_PLUGINS: true同步行为与冲突处理SYNC_SKIP_NEWER_IN_DESTINATION默认 true旧名PLUGINS_SYNC_UPDATE为 true 时以--skip-newer-in-destination参数同步即目标目录中更新的文件不被覆盖——这保证/data卷中手工修改过的插件配置/文件在重启后仍然保留是持久化数据安全的关键默认值REMOVE_OLD_MODSTRUE同步前清空mods/plugins目录中的旧 jar默认仅移除 jar可通过REMOVE_OLD_MODS_INCLUDE、REMOVE_OLD_MODS_EXCLUDE微调REMOVE_OLD_MODS_DEPTH默认 16 控制删除深度。同步时的环境变量插值默认情况下同步采用sync-and-interpolate会对被同步文件中匹配REPLACE_ENV_SUFFIXES默认yml,yaml,txt,cfg,conf,properties,hjson,json,tml,toml后缀且未被排除的文件执行环境变量替换REPLACE_ENV_DURING_SYNCfalse可完全关闭插值退回纯syncREPLACE_ENV_VARIABLE_PREFIX默认CFG_与REPLACE_ENV_VARIABLES_EXCLUDES、REPLACE_ENV_VARIABLES_EXCLUDE_PATHS控制哪些变量参与/排除替换。这一特性意味着你甚至可以在镜像内的插件配置文件中使用${CFG_XXX}占位运行期通过环境变量注入差异化配置。完整的插值语法可参考 docs/configuration/interpolating.md。多源目录COPY_PLUGINS_SRC可以指向多个目录逗号或换行分隔适合公共插件 项目专属插件的分层组织参见 docs/mods-and-plugins/index.mdenvironment: TYPE: PAPER COPY_PLUGINS_SRC: /plugins-common,/plugins-local volumes: - mc-data:/data - ../plugins-common:/plugins-common:ro - ./plugins:/plugins-local:ro构建期打包 vs 运行时挂载如何选择理解了机制后可以清晰对比两种插件供给方式维度构建期打包本文模式运行时挂载/plugins卷插件位置固化在镜像层宿主目录或命名卷分发镜像即完整服务器拉取即用需同时分发插件目录更新插件重新构建镜像替换目录内容后重启容器适用场景团队标准化镜像、CI 产物、可复现部署开发迭代、多服共享插件两条路径共用同一套start-setupMounts同步逻辑与usesPlugins判定区别仅在于/plugins内容来自镜像层还是挂载卷。另需注意容器运行期间新增插件不会被自动加载如 docs/types-and-platforms/server-types/paper.md 所述改动插件后需要重启容器或使用支持热加载的插件配合 reload才能生效。结语examples/paper/paper-build-plugins/plugins/目录虽然只是一个简短的 README却揭示了 docker-minecraft-server 一个极具实用价值的模式把插件打进镜像、让启动脚本自动同步从而获得可复现、可分发、开箱即用的 Minecraft 服务器镜像。结合 scripts/start-setupMounts 的源码与 docs/mods-and-plugins/index.md 的完整变量说明你可以进一步定制同步源、插值行为与旧插件清理策略将该模式推广到 mods 与 config 的打包管理中。【免费下载链接】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），仅供参考