企业官网建设流程全解析

docker-minecraft-server CurseForge模组包自动安装失败速查：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

本文适用场景：docker-minecraft-server 配置MODPACK_PLATFORM: AUTO_CURSEFORGE后，容器启动时下载或安装 CurseForge 模组包失败、反复退出。读完你能从日志判断安装卡在哪一步，并逐项修复，让服务器正常拉起。

📋 动手前检查

一半的安装失败源于前置条件没到位，先确认这五项：

• 已安装 Docker 与 Docker Compose，能正常启动普通容器
• 镜像 tag 与模组包声明的 Java 版本匹配，如itzg/minecraft-server:java17，tag 对照见 Java 版本文档
• EULA: "true"已设置
• CF_PAGE_URL或CF_SLUG指向你要装的模组包
• MEMORY至少4G——镜像默认只有 1G，大型模组包会直接压垮 JVM

🔍 先定位问题

AUTO_CURSEFORGE 的安装逻辑在容器启动早期执行，失败时容器立即退出。对着下面这张表查日志，先判断卡在哪一环：

启动流程大致如下，注意模组包部署发生在世界数据准备之前：

🔧 修复操作

1. API密钥与模组包引用写对

失败最集中在这两个变量上。镜像已内置一个可用的 CurseForge API key，CF_API_KEY仅在你想用自己的密钥时才需要，从 CurseForge 开发者控制台申请即可。用自己的密钥时注意转义规则：

• 直接写在 compose 文件里：密钥中每个$都要写成$$
• 放进与 compose 同目录的.env文件（值用单引号包裹），compose 中写${CF_API_KEY}，.env内不需要再转义

environment: CF_API_KEY: '$$11$$22$$33aaaaaaaaaaaaaaaaaaaaaaaaaa' # 双$转义单个$

模组包引用三选一：页面完整 URLCF_PAGE_URL、模组包 SlugCF_SLUG（页面 URL 中/modpacks/后的短标识）、或固定版本的CF_FILE_ID。想固定版本还可以用CF_FILENAME_MATCHER按文件名子串匹配。引用填错是 "Failed to auto-install" 的第一大原因。

2. 把 Mods Need Download 放进 /downloads

部分模组不允许自动下载，安装日志会以 "Mods Need Download" 列出清单。做法是用浏览器逐个下载，放到本地目录再挂载给容器（容器内路径必须是/downloads，子目录mods、modpacks、worlds都会被查找），然后重新up：

volumes: - ./downloads:/downloads # 把宿主机目录挂进容器

挂载结构如下图所示：

3. 排除客户端专用模组

模组包常携带"客户端专用模组"，服务端加载后会立刻崩溃。把模组的 Slug 或 project ID 写进CF_EXCLUDE_MODS（逗号或空格分隔，支持#注释）。镜像内置规则文件 files/cf-exclude-include.json 默认生效，可用CF_EXCLUDE_INCLUDE_FILE指向自己的 JSON，设为空字符串则禁用。改完规则必须加CF_FORCE_SYNCHRONIZE: "true"强制重新求值，因为排除规则默认只在首次安装时计算：

environment: CF_EXCLUDE_MODS: | # 多行列表，一行一个 creative-core default-options CF_FORCE_SYNCHRONIZE: "true" # 强制重新评估排除规则

4. Java版本与内存对齐

模组包的 Forge/NeoForge 版本绑定特定 Java 版本。装完报class file version说明镜像 Java 太旧；OutOfMemoryError说明内存不够。改 tag 和MEMORY即可：

image: itzg/minecraft-server:java21 # 换成与模组包匹配的Java版本 environment: MEMORY: 4G # 大型模组包建议4G以上

✅ 验证成功

重启后跟一下日志：

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

预期正确结果：日志中不再出现Failed to auto-install CurseForge modpack，模组包安装输出结束后，服务器打印Done并进入就绪状态，此时从客户端连入能正常看到模组加载。如果仍卡住，加DEBUG: "true"让日志输出完整安装命令，再按 排障指南 的方法核对。

⚡ 高频报错速查

相关资源

• AUTO_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