如何使用 Fabric 或 NeoForge 创建模组 Minecraft 服务器
在 VPS 或专用 Linux 服务器上使用 Fabric 或 NeoForge 创建模组 Minecraft 服务器:安装、服务器端和客户端模组、更新以及故障排除。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
模组可以添加内容或改变游戏的运行方式。它们需要加载器才能运行:本指南将 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'然后,每位玩家需要:
- 使用 Fabric 安装器或 NeoForge 安装器,安装相同的 Minecraft 版本和相同的加载器
- 在启动器中运行一次新创建的配置
- 将所需模组(版本须与服务器相同)复制到游戏的
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 关于运行环境的说明。