中文

游戏服务器

如何使用 Fabric 或 NeoForge 创建模组 Minecraft 服务器

在 VPS 或专用 Linux 服务器上使用 Fabric 或 NeoForge 创建模组 Minecraft 服务器:安装、服务器端和客户端模组、更新以及故障排除。

阅读约 9 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

模组可以添加内容或改变游戏的运行方式。它们需要加载器才能运行:本指南将 Fabric 或 NeoForge 安装到单独的文件夹中,不会改动您现有的服务器。

本指南是创建 Minecraft 服务器的延续,沿用其中的 minecraft 用户和 minecraft.service 服务。

完成本指南后,您将拥有:

  • 位于 /opt/minecraft/modded 的模组服务器,由原有服务启动
  • 一个用于下载模组并校验其完整性的脚本
  • 一套判断哪些模组应安装在服务器上、哪些应安装在玩家端的方法
  • 一种恢复到原有服务器的简单方式

前提条件

  • 已按照创建 Minecraft 服务器指南安装好的服务器
  • Java 25,请按照 Paper 指南中安装 Java 25一节的说明安装
  • 使用具有 sudo 权限的用户进行 SSH 访问
  • 为服务器准备至少 4 GB 内存,模组较多时需要更多

检查 Java 并安装本指南使用的工具:

终端
java --version
sudo apt install -y curl jq unzip

第一条命令应显示 openjdk 25 或更高版本。

在 Fabric 和 NeoForge 之间选择

Fabric NeoForge
来源 轻量、模块化的加载器 源自 Forge 的项目
公共基础 Fabric API,许多模组都需要 已集成在加载器中
启动方式 一个 .jar 文件 安装器,然后使用专用的 Java 参数

如何选择主要取决于您想要的模组:模组是针对特定加载器发布的,Fabric 模组无法在 NeoForge 上运行,反之亦然。请先在 Modrinth 上确认它们是否可用。

备份并停止现有服务器

终端
sudo systemctl stop minecraft.service
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-mods-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backups

如果您已部署 Velocity,还请停止占用 25565 端口的 velocity.service。

准备文件夹

创建文件夹并沿用现有服务器的设置:

终端
sudo -u minecraft mkdir -p /opt/minecraft/modded/mods
sudo -u minecraft cp /opt/minecraft/server/server.properties /opt/minecraft/modded/
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=/' \
    -e 's/^server-port=.*/server-port=25565/' \
    -e 's/^online-mode=.*/online-mode=true/' \
    /opt/minecraft/modded/server.properties
echo "eula=true" | sudo -u minecraft tee /opt/minecraft/modded/eula.txt

模组服务器会在 /opt/minecraft/modded/world 中创建一个新世界。

接下来,请只按照以下两节中的一节操作。

安装 Fabric

打开 minecraft 会话,然后获取加载器和安装器的最新稳定版本:

终端
sudo -u minecraft bash
cd /opt/minecraft/modded
MC=26.3
LOADER=$(curl -fsSL "https://meta.fabricmc.net/v2/versions/loader/$MC" | jq -r 'map(select(.loader.stable)) | .[0].loader.version')
INSTALLER=$(curl -fsSL "https://meta.fabricmc.net/v2/versions/installer" | jq -r 'map(select(.stable)) | .[0].version')
echo "Fabric Loader $LOADER, 安装器 $INSTALLER"
curl -fL -o fabric-server.jar "https://meta.fabricmc.net/v2/versions/loader/$MC/$LOADER/$INSTALLER/server/jar"
ls -l fabric-server.jar
exit

如果加载器版本为空或为 null,说明 Fabric 不支持此 Minecraft 版本号:请检查该版本号。

然后让服务指向 Fabric。此文件会补充 minecraft.service,而不会修改它:

终端
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/modded.conf
配置
[Service]
WorkingDirectory=/opt/minecraft/modded
ExecStart=
ExecStart=/usr/bin/java -Xms2G -Xmx4G -jar /opt/minecraft/modded/fabric-server.jar nogui
SuccessExitStatus=130 143
TimeoutStopSec=180

空的 ExecStart= 行用于取消原有命令。请根据您的内存调整 -Xmx,然后前往添加模组。

安装 NeoForge

打开 minecraft 会话,查找适用于您的 Minecraft 版本的最新稳定版本。对于 Minecraft 26.3,NeoForge 的版本号以 26.3.0 开头:

终端
sudo -u minecraft bash
cd /opt/minecraft/modded
PREFIXE=26.3.0
MAVEN=https://maven.neoforged.net/releases/net/neoforged/neoforge
NEO=$(curl -fsSL "$MAVEN/maven-metadata.xml" | grep -F "<version>$PREFIXE." | grep -v beta | sed 's/ *<[^>]*>//g' | sort -V | tail -n 1)
echo "NeoForge $NEO"
curl -fLO "$MAVEN/$NEO/neoforge-$NEO-installer.jar"
echo "$(curl -fsSL "$MAVEN/$NEO/neoforge-$NEO-installer.jar.sha256")  neoforge-$NEO-installer.jar" | sha256sum -c -
java -jar "neoforge-$NEO-installer.jar" --installServer
printf -- '\n-Xms2G\n-Xmx4G\n' >> user_jvm_args.txt
ls
exit

安装器会下载 Minecraft 服务器及其依赖库。完成后,您应该看到 run.sh、user_jvm_args.txt 和 libraries 文件夹。

让服务指向 NeoForge。run.sh 脚本会使用正确的参数启动 Java,并且在更新后依然有效:

终端
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/modded.conf
配置
[Service]
WorkingDirectory=/opt/minecraft/modded
ExecStart=
ExecStart=/bin/sh /opt/minecraft/modded/run.sh nogui
SuccessExitStatus=130 143
TimeoutStopSec=180

内存在 user_jvm_args.txt 中设置。

添加模组

创建一个脚本,用于从 Modrinth 获取模组、校验其哈希值、排除仅限客户端的模组并提示依赖项:

终端
sudo nano /opt/minecraft/mod-get.sh
终端
#!/bin/bash
# 从 Modrinth 下载适用于服务器的模组最新稳定版本
set -euo pipefail

MOD="${1:?请指定模组,例如 lithium}"
CHARGEUR="${2:?请指定加载器:fabric 或 neoforge}"
MC_VERSION="${3:?请指定 Minecraft 版本,例如 26.3}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://api.modrinth.com/v2"

cd /opt/minecraft/modded/mods

VERSION=$(curl -fsSL -H "User-Agent: $UA" -G "$API/project/$MOD/version" \
    --data-urlencode "loaders=[\"$CHARGEUR\"]" \
    --data-urlencode "game_versions=[\"$MC_VERSION\"]" \
    --data-urlencode "include_changelog=false" \
    | jq -c 'map(select(.version_type == "release")) | .[0]')
if [ "$VERSION" = "null" ]; then
    echo "未找到稳定版本:$MOD ($CHARGEUR $MC_VERSION)" >&2
    exit 1
fi

ENVIRONNEMENT=$(echo "$VERSION" | jq -r '.environment // "unknown"')
case "$ENVIRONNEMENT" in
    client_only|singleplayer_only)
        echo "$MOD 无法安装到服务器 ($ENVIRONNEMENT)。" >&2
        exit 1
        ;;
esac

FICHIER=$(echo "$VERSION" | jq -c '(.files | map(select(.primary)) | .[0]) // .files[0]')
NOM=$(basename "$(echo "$FICHIER" | jq -r '.filename')")
URL=$(echo "$FICHIER" | jq -r '.url')
SHA512=$(echo "$FICHIER" | jq -r '.hashes.sha512')

curl -fL -H "User-Agent: $UA" -o "$NOM.part" "$URL"
echo "$SHA512  $NOM.part" | sha512sum -c -
mv "$NOM.part" "$NOM"
echo "$NOM 已就绪 (环境:$ENVIRONNEMENT)。"

for ID in $(echo "$VERSION" | jq -r '.dependencies[]? | select(.dependency_type == "required") | .project_id // empty'); do
    echo "必需依赖:$(curl -fsSL -H "User-Agent: $UA" "$API/project/$ID" | jq -r '.slug')"
done

替换 UA 这一行中的 your-domain.com,然后使脚本可执行:

终端
sudo chmod 755 /opt/minecraft/mod-get.sh

传给脚本的名称取自模组在 Modrinth 上的地址:modrinth.com/mod/lithium 对应 lithium。下面是两个示例,使用的是 Lithium,这是一款优化模组,玩家无需安装即可生效。

使用 Fabric 时,还需添加大多数模组都需要的 Fabric API:

终端
sudo -u minecraft /opt/minecraft/mod-get.sh fabric-api fabric 26.3
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3

使用 NeoForge 时:

终端
sudo -u minecraft /opt/minecraft/mod-get.sh lithium neoforge 26.3

每一行 .part: OK 都表示下载的文件完好无损。对于显示的每个 必需依赖,也请使用同样的命令进行安装。

启动服务器

终端
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -f

首次启动耗时较长,因为需要创建世界。当出现 Done (…)! For help, type "help" 这一行时,服务器即已就绪。按 Ctrl+C 退出日志跟踪。

验证结果

终端
systemctl show minecraft.service -p WorkingDirectory
sudo ls -l /opt/minecraft/modded/mods
sudo journalctl -u minecraft.service --since "15 minutes ago" --no-pager | grep -iE 'fabric loader|loading [0-9]+ mods|neoforge|done \('

工作目录应为 /opt/minecraft/modded。使用 Fabric 时,日志会显示 Loading Minecraft 26.3 with Fabric Loader 以及模组数量。使用 NeoForge 时,日志会在启动时提到 NeoForge。无论哪种情况,都应出现 Done 这一行,且其上方没有模组错误。

如果您已按照 Paper 指南创建了 mc-console 命令,它仍然可用,因为服务没有变化:sudo mc-console list。

在客户端安装模组

并非所有模组都安装在同一位置。在 Modrinth 上,每个版本都标明了运行环境,脚本会将其显示出来:

环境 服务器 玩家
client_and_server 是 是
server_only、dedicated_server_only 是 否
server_only_client_optional 是 可选
client_only 否 是
client_only_server_optional 可选 是
client_or_server 二者之一即可 二者之一即可
client_or_server_prefers_both 建议安装 建议安装
singleplayer_only 否 仅限单人游戏
unknown 请查看模组页面 请查看模组页面

例如,Sodium 仅用于客户端,FabricProxy-Lite 仅用于专用服务器。添加方块或物品的模组几乎总是需要在两端同时安装。

对于已下载的 Fabric 模组,其文件也可能标明适用的一端。以下命令会显示 client、server 或表示两端的 *;如果该字段不存在,则不显示任何内容,这等同于 *:

终端
sudo unzip -p /opt/minecraft/modded/mods/模组名称.jar fabric.mod.json | jq -r '.environment // empty'

然后,每位玩家需要:

  1. 使用 Fabric 安装器或 NeoForge 安装器,安装相同的 Minecraft 版本和相同的加载器
  2. 在启动器中运行一次新创建的配置
  3. 将所需模组(版本须与服务器相同)复制到游戏的 mods 文件夹
系统 mods 文件夹
Windows %APPDATA%\.minecraft\mods
macOS ~/Library/Application Support/minecraft/mods
Linux ~/.minecraft/mods

对于玩家群体,整合包可以避免版本差异:发布一份明确的清单,或发布 Modrinth 格式的整合包,供每位玩家导入启动器。如果整合包提供“服务器”版本,请在服务器端使用该版本。

备份模组服务器

基础指南的 backup.sh 脚本不包含此文件夹。请在 /opt/minecraft/backup.sh 中现有的 tar 行之后添加这一行。world_ 前缀可让自动清理将其纳入处理:

终端
tar -czf $BACKUP_DIR/world_modded_$DATE.tar.gz -C /opt/minecraft/modded world mods config server.properties

更新

更新前请务必在服务器停止时进行备份:

终端
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/modded-$(date +%F-%H%M).tar.gz -C /opt/minecraft modded

要更新模组,请删除其旧文件,然后重新运行脚本:

终端
sudo ls /opt/minecraft/modded/mods
sudo -u minecraft rm /opt/minecraft/modded/mods/lithium-fabric-旧版本.jar
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3
sudo systemctl start minecraft.service

要更新加载器,请重新运行其安装章节中的命令(NeoForge 需省略 printf 这一行),然后检查 user_jvm_args.txt 中的内存设置。如果玩家端也安装了相应的模组或加载器,请将变更告知玩家。

恢复到原有服务器

移除服务的补充配置。您的 /opt/minecraft/server 文件夹未被修改:

终端
sudo systemctl stop minecraft.service
sudo rm /etc/systemd/system/minecraft.service.d/modded.conf
sudo systemctl daemon-reload
sudo systemctl start minecraft.service

/opt/minecraft/modded 文件夹会保留:重新创建 modded.conf 文件即可切换回来。如果您使用 Velocity,还请重启 velocity.service。

故障排除

终端
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/modded/logs/latest.log

崩溃报告位于 /opt/minecraft/modded/crash-reports。

“Incompatible mods found!”(Fabric)

该消息会列出相关模组,并带有 requires … which is missing! 或 but only the wrong version is present 之类的行。请安装缺失的依赖项(通常是 fabric-api),或选用兼容的版本。

“Cannot load class … in environment type SERVER”

服务器上存在仅限客户端的模组。请移除报告中提到的模组。使用 NeoForge 时,同样的问题通常表现为 net/minecraft/client/… 类的 NoClassDefFoundError。

“Mod … requires …”(NeoForge)

缺少依赖项,或其版本不正确。该消息会指出需要安装的模组和所需版本。

“Mod … is present in multiple files”

使用 NeoForge 时,mods 中存在同一模组的两个版本。请保留较新的版本。使用 Fabric 时,同样每个模组只保留一个文件。

“You are trying to connect to a server that is running NeoForge, but you are not”

玩家启动游戏时未使用 NeoForge。玩家需要安装提示的版本,并在启动器中选择该配置。

“Your client is missing the following mods”

使用 NeoForge 时,连接界面会列出玩家需要添加的模组。The following mod versions do not match 表示版本不一致:请将其调整为与服务器相同的版本。

“Received a registry entry that is unknown to this client”

使用 Fabric 时,客户端和服务器的内容类模组不一致。请对比两边的列表,包括版本。

“Incompatible client! Please use …”

客户端使用的 Minecraft 版本与服务器不同。请在启动器中选择正确的配置。

“UnsupportedClassVersionError”

对于此服务器或某个模组而言,Java 版本过旧。请检查 java --version,然后参阅安装 Java 25一节。

“FAILED TO BIND TO PORT”

另一个服务占用了 25565 端口,通常是 Velocity。请使用 sudo ss -ltnp | grep 25565 找出该服务。

mod-get.sh 脚本失败

  • 未找到稳定版本:该模组没有适用于此加载器和此版本的发布
  • curl 报告 404 错误:模组名称不正确
  • 无法安装到服务器:此模组只能安装在玩家端
  • sha512sum: WARNING:下载的文件已损坏。请重新运行脚本

如需进一步了解,请查阅 Fabric 文档、NeoForge 服务器指南以及 Modrinth 关于运行环境的说明。