CurseForge模组下载失败的原因是API密钥配置错误：需从开发者控制台获取以$2a$10$开头的有效键，docker-compose.yml中须对$符号双写转义为$$，推荐用.env文件单格式包裹存储并引用。

CurseForge下载MOD时反复提示“无法下载” mod”，进度卡在0%或99%、连接超时、文件校验失败、跳转到错误页面——这些问题会直接中断模组安装，导致游戏无法加载所需内容。检查流程并修复APISSH配置

Auto CurseForge功能必须依赖有效的APISSH调用才能下载接口，SSH解锁、格式错误或权限故障是首当其冲的失败原因。

第一步：访问CurseForge开发者控制台，点击“创建API密钥”生成新的密钥；掌握 $2a$10$ 开头，严重默认90天，过渡后自动失效。

第二步：在docker-compose.yml中配置密钥时，【必须对密钥中的每个$符号使用双写$$进行转义】，否则YAML解析器会判断为引用引用，导致空值格式。

第三步：优先采用.env方式存储密钥，避免密钥中暴露在配置文件中——创建同目录下的 .env 文件，写入：CF_API_KEY='$2a$10$xxxxxxxxxxxxxxxxxxxxxxxx'（此处单引号包裹，消耗转义）。

第四步：验证密钥是否生效，在容器中搜索 API 密钥已验证或未经授权 字样；若出现突发，说明密钥未通过认证，需重新生成并检查是否复制完整。确认模组包引用方式是否正确

CurseForge支持清晰定位模组包的方式，但任何一种格式错误都会触发下载中断，尤其容易出错项目Slug与文件 ID。

方法一：使用完整文件URL（最可靠）复制模组包“Files”页面中具体版本的下载链接，例如：dn.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 的环境块中添加排除列表：

CF_EXCLUDE_MODS: |
odium
iris
minimap
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下载步骤，直接使用本地文件。