curseforge模组下载失败的首要原因是api密钥配置错误：需从开发者控制台获取以$2a$10$开头的有效密钥，docker-compose.yml中须对$符号双写转义为$$，推荐用.env文件单引号包裹存储并引用。
CurseForge下载MOD时反复提示“Failed to download mod”，进度卡在0%或99%、连接超时、文件校验失败、跳转到错误页面——这些问题会直接中断模组安装流程，导致游戏无法加载所需内容。
检查并修复API密钥配置
Auto CurseForge功能必须依赖有效API密钥才能调用下载接口，密钥缺失、格式错误或权限失效是首当其冲的失败原因。
第一步：访问 CurseForge开发者控制台，点击“Create API Key”生成新密钥；密钥以 $2a$10$ 开头，有效期默认90天，过期后自动失效。
第二步：在 docker-compose.yml 中配置密钥时，【必须对密钥中的每个 $ 符号使用双写 $$ 进行转义】，否则YAML解析器会误判为变量引用，导致空值传入。
第三步：优先采用 .env 文件方式存储密钥，避免密钥明文暴露在配置文件中——创建同目录下的 .env 文件，写入：CF_API_KEY='$2a$10$xxxxxxxxxxxxxxxxxxxxxxxxxx'（此处单引号包裹，无需转义）。
第四步：验证密钥是否生效，在容器日志中搜索 API key validated 或 Unauthorized 字样；若出现后者，说明密钥未通过认证，需重新生成并检查是否复制完整。
确认模组包引用方式是否正确
CurseForge支持三种定位模组包的方式，但任意一种格式出错都会触发下载中断，尤其容易混淆项目Slug与文件ID。
方法一：使用完整文件URL（最可靠）
复制模组包“Files”页面中具体版本的下载链接，例如：https://media.forgecdn.net/files/4248/390/AllTheMods8-1.20.1-1.12.0.zip，填入 CF_PAGE_URL 环境变量。
方法二：组合Slug + 文件ID（需手动查找）
Slug是URL中斜杠后的短标识，如 all-the-mods-8；文件ID是“Files”页每行右侧数字，如 4248390；二者必须严格匹配同一版本，【Slug填错或文件ID对应旧版本，会导致404错误】。
方法三：用版本匹配器模糊定位
设置 CF_FILENAME_MATCHER: "1.20.1"，让程序自动筛选含该字符串的文件名；但此方式依赖文件命名规范，部分作者不按惯例命名，可能漏选或误选。
排除客户端专用Mod干扰
服务器启动失败常因加载了仅适用于客户端的模组，如光影引擎（Iris/Sodium）、HUD增强（KubeJS Client）、资源包加载器等，这些模组在服务端会触发 NoClassDefFoundError: net/minecraft/client/ 类缺失异常。
在 docker-compose.yml 的 environment 区块中添加排除列表：
CF_EXCLUDE_MODS: |<br> sodium<br> iris<br> minimap<br> reese-sodium-options
注意每行缩进必须为两个空格，且不能混用Tab；排除项填写的是Mod项目ID（即其CurseForge页面URL中最后一段），不是文件名。
若需更精细控制，可创建 cf-exclude-include.json 文件，通过 CF_EXCLUDE_INCLUDE_FILE 指向该路径，支持正则匹配和条件排除。
手动补全缺失文件
部分模组因版权或地域限制无法通过API直链下载，容器日志中会出现 Mods Need Download 提示，并附带缺失文件的原始下载地址。
创建本地 downloads/ 目录，将其挂载进容器：- ./downloads:/downloads。
从日志中复制缺失文件的完整URL，在浏览器中打开并手动下载，保存至 downloads/ 目录下，文件名保持原始名称（不要重命名）。
重启容器，程序会自动扫描该目录并跳过API下载步骤，直接使用本地文件。
