企业官网建设流程全解析

Docker Minecraft Server CurseForge模组包自动安装失败快速排查：完整分步指南

【免费下载链接】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 镜像可以在启动时自动安装 CurseForge 模组包，但实际使用中常出现安装失败、模组缺失或服务器启动崩溃。本文按"看日志定位原因 → 逐项修正配置"的顺序分步讲解，帮你把卡住的模组包服务器跑起来。

是否卡在了同一处？

如果日志中出现以下任意一条，基本可以确认是模组包自动安装环节的问题：

• 日志以Failed to auto-install CurseForge modpack结尾，容器直接退出
• 反复出现Re-installing due to missing files from modpack，模组永远缺几个
• 日志输出Mods Need Download列表，这些文件没有自动下载
• Java 版本不匹配的报错（如Unsupported class file major version），或 JVM 启动即崩溃

先用两条命令定位原因 🛠️

第一条，抓安装阶段的错误关键字：

docker compose logs mc 2>&1 | grep -iE "auto-install|Mods Need Download|401|OutOfMemory"

第二条，确认镜像的 Java 版本标签：

docker image inspect itzg/minecraft-server -f '{{.Config.Labels."org.opencontainers.image.version"}}'

最可能的三个成因，按概率从高到低：

1. API 密钥失效：密钥直接写在 compose 里且$未转义，被 compose 变量替换吞掉，请求 CurseForge 全部 401
2. 内存不足：MEMORY默认只有 1G，大型模组包在解压和拷贝模组阶段 OOM
3. Java 标签不匹配：模组包声明需要 Java 21，镜像却用了 java17，模组无法加载

跟着做，分步解决

1. 把镜像 Java 版本对齐模组包要求。将 image 标签改为java17、java21等，对照 Java 版本选择文档。预期结果：日志不再出现类版本报错；失败则查该文档中的版本对应表。

2. 配置 API 密钥。把密钥放进 compose 同目录的.env文件（用单引号包裹，无需转义），compose 中以${CF_API_KEY}引用；如果必须直接写在 compose 里，$要写成$$。参考 ATM8 完整示例：

   environment: MODPACK_PLATFORM: AUTO_CURSEFORGE CF_API_KEY: ${CF_API_KEY} CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8 MEMORY: 4G

   预期结果：日志中不再出现 401 或权限类错误；失败则重点检查密钥里是否有未转义的$、密钥是否过期。

3. 给足内存。模组包建议MEMORY: 4G起步，大型包 6-8G。预期结果：安装全程无 OOM；仍不足就查看日志里 JVM 的内存告警输出。

4. 补上手动下载项。日志Mods Need Download列出的文件需用浏览器下载，放入./downloads/mods/，挂载./downloads:/downloads后重新docker compose up -d。预期结果：日志走到Done，不再提示手动下载；仍提示则核对文件名与列表是否完全一致。

怎么确认已经修好？

docker compose up -d mc && docker compose logs -f mc

两个正常标志：日志走到Done (XXs)并继续出现 Java 进程启动信息；客户端实际连入服务器后不报错。定位不了问题时开调试模式兜底：DEBUG: "true"输出完整安装过程，DEBUG_EXEC: "true"输出最终启动命令，详见 故障排除指南。

还是不行？ ⚠️

• 症状：反复重启并提示Re-installing due to missing files。 原因：个别模组使用后会自删除或改写，安装器误以为文件缺失。 配置：CF_IGNORE_MISSING_FILES: mods/gregtech-*.jar（换成你日志里的具体文件）。
• 症状：下载卡住、极慢或超时。 原因：默认 4 路并行下载把带宽打满。 配置：CF_PARALLEL_DOWNLOADS: "2"。
• 症状：装完启动即崩，日志显示客户端模组冲突。 原因：客户端专用模组没被排除。 配置：CF_EXCLUDE_MODS: creative-core,default-options，改完后加一次CF_FORCE_SYNCHRONIZE: "true"重新同步。

下次别再踩这个坑

• 锁定版本：用CF_FILE_ID或CF_FILENAME_MATCHER固定模组包版本，避免每次启动都漂移到最新版导致"昨天还好好的"。
• 预留资源：大型模组包直接给 6-8G 内存，模组加依赖轻松超过 10G 磁盘，别按 1G 默认值省着来。
• 定期更新镜像：安装器本身也在持续修复 bug，长期用旧镜像会错过下载相关的修复。

参考资料

• CurseForge 模组包自动安装（AUTO_CURSEFORGE）文档
• CurseForge 单个模组自动下载文档
• 故障排除与调试指南
• ATM8 完整示例配置

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