说到CurseForge下载模组失败，最常踩的坑是API密钥配置问题。

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 下载步骤。

《夸克》非常好用的免费AI浏览器

下载APP查看