说到CurseForge模组下载失败，最常见的错误原因之一是API密钥配置出错。从开发者控制台获取的密钥以$2a$10$开头，这一点至关重要。然而，问题往往出现在配置环节——如果你直接将密钥写入docker-compose.yml，请务必把每个$符号替换为$$，否则YAML解析器会错误地将$当作变量引用，最终传入空值，导致接口无法访问。
更推荐的稳妥做法是，单独创建一个.env文件，用单引号将密钥包裹后放入其中，然后在配置文件中引用该变量。这样既能避免密钥明文暴露，也省去转义步骤。容器启动后，建议检查日志，看到API key validated才说明链路通畅。如果出现Unauthorized错误，请重新生成密钥，不要图省事。
另一个常见报错是下载进度卡在0%或99%，甚至直接跳转至错误页面。这通常与模组包的引用方式不当有关。CurseForge支持三种定位方式，但每种方式都有其使用要点。
最可靠的是直接使用完整文件URL——进入模组包的“Files”页面，找到对应版本，复制以https://media.forgecdn.net/files/开头的链接，填入CF_PAGE_URL环境变量，通常不会出错。
第二种方式结合了Slug和文件ID。Slug即URL中的短标识，例如all-the-mods-8；文件ID是“Files”页面每行右侧的数字。两者必须严格匹配同一个版本，不可混用。Slug填错或文件ID指向旧版本，都会导致404错误。
第三种是使用版本匹配器进行模糊定位，例如设置CF_FILENAME_MATCHER: "1.20.1"，让程序自动筛选。但这种方式依赖文件名规范，若作者命名不标准，可能出现漏选或误选，仅作为最后的备用方案。
服务器启动失败还有一个极易被忽视的原因——混入了客户端专用模组。例如光影引擎（Iris/Sodium）、HUD增强（KubeJS Client）等，在服务端无法运行，启动时会报NoClassDefFoundError: net/minecraft/client/。解决方法是在docker-compose.yml的environment区块中添加排除列表：
CF_EXCLUDE_MODS: | sodium iris minimap reese-sodium-options
注意每行缩进必须是两个空格，不能混用Tab。填写的是Mod的项目ID，即CurseForge页面URL最后一段，请勿混淆。如果需要更精细的控制，可以编写cf-exclude-include.json文件，支持正则匹配，灵活性更高。
最后，部分模组因版权或地域限制无法通过API直链下载。此时日志会提示Mods Need Download，并附上缺失文件的原始下载地址。手动在浏览器中打开链接，将文件下载至本地downloads/目录，然后将该目录挂载到容器中。重启后，程序会自动识别并使用本地文件，跳过API下载步骤。
