上手

三分钟上手

如果你只想尽快跑通一次，照下面五步做就行。每一步后面的「→ 你会看到」是做对了应该出现的现象；没出现，就翻到「出问题了怎么办」。

第 1 步

找到你的 mods 文件夹

服务端的 mods 文件夹通常在服务端根目录下，路径长这样：C:\servers\survival\mods。

你不需要把它拷到别的地方，也不用先关服。整个过程里这个文件夹都是只读的。

C:\servers\survival\
|-- mods\                 # 就是它
|   |-- fabric-api-0.92.2.jar
|   `-- sodium-0.6.5.jar
|-- server.jar
`-- server.properties

你会看到：一个装着若干 .jar 文件的文件夹。工具只读它们的文件名和 jar 内部的元数据，不会修改、移动、删除或新增任何文件。

第 2 步

建立清单

图形界面版：菜单「清单 → 扫描 mods 文件夹…」，选中上一步那个文件夹。

命令行版：启动后在主菜单里选 2。

「清单」是 modcheck 的说法，指一份「这台服务器上装了哪些模组」的记录。建一次，以后每次检查都复用它。

你会看到：先是进度条扫过文件夹，然后提示「正在联网识别」，稍等一会儿提示识别出 N 个模组。这一步要拿着每个 jar 去 Modrinth 和 CurseForge 查一次 —— 模组越多越慢，属于正常现象。

第 3 步

给清单起个名字并保存

名字随你起，比如「生存服」。它只用来区分不同的服务器或整合包，不影响判定结果，带空格或中文都没问题。

你会看到：提示清单已保存，并告诉你这份清单里有多少个模组。清单文件存在程序同级的 config 目录里。

第 4 步

做一次检查

选清单（生存服）→ 选目标版本（比如 26.3）→ 选加载器（多数情况是 Fabric）→ 点「开始检查」。

你会看到：进度逐个模组推进，结束后出现一条结论横幅，告诉你这份清单整体的结论。120～200 个模组的首次检查通常要 1～3 分钟。

第 5 步

看结论并处理

结果按状态分成几个页签。点某一行，下方会显示这个模组的详情和建议。

六种状态分别是什么意思、你该做什么
状态	含义	你该做什么
就绪	目标版本上有可用版本	不用管
需注意	最新正式版不支持，但有更早的稳定版可用	用那个旧稳定版，别下最新版
仅存测试版	只有 alpha/beta 支持目标版本	自行评估风险，建议先备份存档
阻塞	目标版本上没有任何可用版本	必须先解决，否则无法升级
未判定	没查到（不算失败）	可稍后重跑；必要时手动指定平台项目
已忽略	你主动标记为不参与检查	不参与判定

你会看到：状态里没有「未知」这个词。查不到就是「未判定」，它不会替你挑一个版本填上去。

出问题了怎么办

下面这些是最常遇到的几种。点开看具体怎么办。

联网识别很慢，是不是卡住了？

不是。识别是逐个模组去 Modrinth 和 CurseForge 查询，第一次跑一定是这样，30 个模组就要查 30 次，网络不好时会更久。

耐心等它走完。中途关掉窗口会白跑一趟 —— 已经查到的部分会留在缓存里，但这一次的识别不算完成。

有些模组显示「未判定」，是出错了吗？

不是。「未判定」只表示这个模组在平台上的信息没查到，不代表它不兼容，更不算失败。

常见原因有三种：这个模组只发在 CurseForge 或只发在作者自己的网站上；jar 里的名字和平台上的项目名对不上；平台暂时还没收录。

可以先稍后重跑一次。如果一直查不到，就手动指定这个模组对应的平台项目 —— 与其让它猜，不如你告诉它。

怎么指定：图形界面版走菜单 清单 → 管理模组清单…，在右侧列表里选中那个模组，点底部的 「指定平台项目」，然后从搜索结果里挑出正确的项目。命令行版的主菜单里，[3] 管理模组清单 → 打开对应清单 → [3] 指定平台项目（手动匹配），按提示输入模组编号或名称即可。

指定之后它会记住，后续检查不再重复问你。

单文件版双击一闪而过，什么都没发生

单文件版每次启动都会先把自己解包到系统临时目录再运行，这一步可能被杀毒软件拦下来，表现就是窗口一闪就没。

换成免安装目录版（modcheck-<版本>-cli-standalone.zip）。它不需要临时解包，被拦下来的概率低很多，启动也更快。

配置和清单存在哪？换电脑怎么办？

都存在程序同级的 config 目录里 —— 绿色便携，不写注册表，不碰系统目录。

把整个程序文件夹拷到新机器上，清单和设置就都跟着走了，不用重新扫一遍 mods 文件夹。

第二次检查为什么快这么多？

因为命中了缓存：上一次查到的版本信息会存下来，短期内再查同一个模组就直接读本地，不再联网。Modrinth 的数据默认缓存 6 小时。

想让它重新联网查一遍，跑的时候加上 --refresh，或者清掉缓存。

图形界面版解压后双击没反应

先确认是「解压之后」再运行，而不是在压缩包预览窗口里直接双击。图形界面版需要旁边的 Qt 运行库和 Python 运行环境才能起来，把 exe 单独拖出来是跑不起来的。

如果确实已经解压，试试同目录下的 启动GUI.cmd；还是不行的话，用命令行版跑一次，它的报错信息更直白。

不知道该选哪个加载器

看你的服务端是用哪个启动脚本或启动 jar 起的：名字里带 fabric 的就是 Fabric，带 neoforge 的是 NeoForge，带 forge 的是 Forge。

如果服务端根本没装加载器，那也就没有模组需要检查了。

命令行速查

图形界面版能做的事，命令行版都能做 —— 它们跑的是同一份判定代码。

交互用法：运行 启动CLI.cmd，主菜单按数字选；建立清单是 2。

脚本用法：

# 扫描 mods 文件夹，建立清单
modcheck scan "C:\servers\survival\mods" --profile 服务器A

# 跑一次检查
modcheck check --profile 服务器A --mc 26.3 --loader fabric

# 同时导出 JSON 和 Markdown 报告
modcheck check --profile 服务器A --mc 26.3 --loader fabric --json report.json --md report.md

# 忽略缓存，强制重新联网查一遍
modcheck check --profile 服务器A --mc 26.3 --loader fabric --refresh

常用参数

最常用的几个参数
参数	作用
`--profile <名字>`	用哪份清单
`--mc <版本>`	目标 Minecraft 版本，例如 26.3
`--loader <加载器>`	Fabric、NeoForge 或 Forge
`--mods-dir <目录>`	直接指定 mods 文件夹，跳过清单
`--json <文件>`	额外导出 JSON 结果
`--md <文件>`	额外导出 Markdown 报告
`--refresh`	忽略缓存，强制重新请求
`--jobs <n>`	并发查询数
`--quiet`	「就绪」那一组只显示数量
`--pre`	把 beta / alpha 也算作可用
`--yes`	非交互，一律取默认值
`--no-color`	关闭彩色输出，进日志和 CI 时用

退出码

退出码对照
退出码	什么情况下会出现
`0`	全部就绪，或者只有「需注意」「仅存测试版」
`1`	存在「阻塞」项
`2`	存在「未判定」项，且没有「阻塞」项
`3`	参数或配置错误
`4`	数据源整体不可用（连不上 Modrinth）
`130`	被中断（Ctrl+C）

同时命中多个条件时只返回一个，优先级是 3 > 4 > 130 > 1 > 2 > 0。

术语表

这几个词在页面里反复出现，先认识一下。

加载器（loader）: 让模组跑起来的服务端框架。常见的有 Fabric、NeoForge、Forge。同一个模组往往为不同加载器分别发布，所以检查时必须指定加载器。
清单（profile）: 一份「这台服务器上装了哪些模组」的记录。建立一次，之后每次检查都复用它。
正式版（release）: Mojang 发布的稳定版本，比如 26.3。判定默认针对正式版。
快照（snapshot）: 两次正式版之间的预览版本。本工具不做快照版本检查。
alpha / beta: 模组作者发布的测试版本。只有测试版支持目标版本时，状态是「仅存测试版」。
未判定（Undetermined）: 没查到可用信息。它既不是失败，也不是「不兼容」。重跑一次，或者手动指定平台项目。

下一步

跑通了一次，接下来就是把它用在你真正要升级的那台服务器上。

下载 modcheck 还可以让它自动下模组