中文

游戏服务器

如何安装和配置 EssentialsX

在您的 Minecraft Paper 服务器上安装 EssentialsX:家(home)、传送点(warp)、传送、礼包(kit)、经济和聊天,并配置相应的 LuckPerms 权限。

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

本页内容

EssentialsX 为您的服务器添加玩家期待的命令:/home、/spawn、/tpa、/warp、/msg,以及礼包和经济系统。本指南介绍如何在 Paper 上安装它、授予合适的权限,并调整最实用的选项。

前提条件

本指南中的 Steve 仅为示例:请替换为真实的玩家名。

选择合适的版本

要安装的版本取决于您的 Minecraft 版本。请使用 sudo mc-console version 查看。

Minecraft 要安装的 EssentialsX
26.2 或 26.3 开发构建 2.22.1
26.1.2 或 1.21.11 稳定版 2.22.0

选择模块

EssentialsX 分为多个文件,只有第一个是必需的。

模块 作用 在本指南中
EssentialsX 主要命令、礼包、经济 必需
EssentialsX Spawn 出生点、/spawn、/setspawn 安装
EssentialsX Chat 聊天格式、前缀和后缀 安装
EssentialsX AntiBuild 按权限允许或禁止建造 可选
EssentialsX Protect 世界设置:苦力怕伤害、火势蔓延 可选
EssentialsX GeoIP 玩家的大致位置 可选
EssentialsX Discord 和 Discord Link 与 Discord 的桥接和账户关联 可选
EssentialsX XMPP XMPP 桥接,历史遗留模块 可选

安装 Vault 和 EssentialsX

Vault 让 EssentialsX 能够读取 LuckPerms 的组和前缀。没有它,前缀和与组相关的功能将无法工作。

下载 Vault,然后下载适用于 Minecraft 26.3 的开发构建的三个模块:

终端
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
curl -fL -o Vault.jar https://github.com/MilkBowl/Vault/releases/latest/download/Vault.jar
BASE="https://ci.ender.zone/job/EssentialsX/lastSuccessfulBuild"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
    FICHIER=$(curl -fsSL "$BASE/api/json?tree=artifacts%5BfileName%5D" | jq -r --arg m "$MODULE" '.artifacts[].fileName | select(startswith($m + "-"))')
    curl -fL -o "$FICHIER" "$BASE/artifact/jars/$FICHIER"
done
ls -l Vault.jar EssentialsX*.jar
exit

对于 Minecraft 26.1.2 或 1.21.11,请改用稳定版,以代替上面的循环:

终端
BASE="https://github.com/EssentialsX/Essentials/releases/download/2.22.0"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
    curl -fLO "$BASE/$MODULE-2.22.0.jar"
done

重启服务器并等待出现 Done 这一行:

终端
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f

验证安装

按 Ctrl+C 退出日志跟踪,然后运行:

终端
sudo mc-console plugins
sudo mc-console vault-info
sudo mc-console 'essentials version'

您应该看到:

  • 插件列表中有 Essentials、EssentialsChat、EssentialsSpawn、LuckPerms 和 Vault
  • vault-info 的响应中有 Permission: LuckPerms 和 Chat: LuckPerms
  • 同一响应中有 Economy: Essentials Economy
  • essentials version 中所有模块的版本相同

配置文件位于 /opt/minecraft/server/plugins/Essentials。

为玩家授予权限

OP 可以使用所有功能。其他玩家在获得相应权限之前,无法使用任何 EssentialsX 命令。

为所有玩家授予常用命令:

终端
for PERM in spawn home sethome delhome tpa tpaccept tpdeny back warp warp.list msg afk list motd rules help balance pay kit kits.tools; do
    sudo mc-console "lp group default permission set essentials.$PERM true"
done

然后补充更高等级的权限:

终端
for PERM in sethome.multiple sethome.multiple.vip fly; do
    sudo mc-console "lp group vip permission set essentials.$PERM true"
done
for PERM in tp tphere kick mute tempban; do
    sudo mc-console "lp group moderator permission set essentials.$PERM true"
done
for PERM in setspawn setwarp delwarp eco createkit; do
    sudo mc-console "lp group admin permission set essentials.$PERM true"
done
命令 效果 权限
/spawn 返回出生点 essentials.spawn
/sethome [名称] 和 /home [名称] 创建家并前往 essentials.sethome、essentials.home
/delhome <名称> 删除家 essentials.delhome
/tpa <玩家> 请求传送到某位玩家处 essentials.tpa
/tpaccept 和 /tpdeny 接受或拒绝请求 essentials.tpaccept、essentials.tpdeny
/back 返回上一个位置 essentials.back
/warp [名称] 列出传送点或前往传送点 essentials.warp、essentials.warp.list
/msg <玩家> <消息> 和 /r <消息> 私信和回复 essentials.msg
/balance 和 /pay <玩家> <金额> 余额和付款 essentials.balance、essentials.pay
/kit [名称] 列出礼包或领取礼包 essentials.kit、essentials.kits.<名称>

完整权限列表可在项目网站上查看。

调整配置

以 minecraft 用户身份打开文件:

终端
sudo -u minecraft nano /opt/minecraft/server/plugins/Essentials/config.yml

在 nano 中,按 Ctrl+W 可搜索选项。请修改现有的行,不要添加新行,并且只使用空格进行缩进。

YAML
# 消息语言(此行默认处于注释状态)
locale: zh

# 两次传送之间的等待时间(秒)
teleport-cooldown: 30

# 传送前的延迟,玩家移动或受到攻击时取消
teleport-delay: 3

# 初始余额和货币
starting-balance: 100
currency-symbol: '€'
currency-symbol-suffix: true

家的数量按级别设置。没有 essentials.sethome.multiple 的玩家只能拥有一个家。拥有此权限的玩家获得 default 的值,而 essentials.sethome.multiple.vip 则赋予其 vip 的值:

YAML
sethome-multiple:
  default: 3
  vip: 5
  staff: 10

无需重启即可应用更改:

终端
sudo mc-console 'essentials reload'

设置出生点和传送点

这些命令需在游戏中的目标位置输入,并使用 OP 账户或 admin 组成员的账户:

文本
/setspawn
/setspawn newbies
/setwarp boutique

/setspawn 设置全局出生点。/setspawn newbies 设置新玩家的出生点,通过 config.yml 中的 newbies 选项使用:

YAML
newbies:
  announce-format: '&d欢迎 {DISPLAYNAME}&d 来到服务器!'
  spawnpoint: newbies
  kit: tools

指定的礼包会在首次连接时发放,不检查权限。设置 kit: '' 可将其禁用。

创建礼包

礼包位于 plugins/Essentials/kits.yml:

终端
sudo -u minecraft nano /opt/minecraft/server/plugins/Essentials/kits.yml

将您的礼包添加到 kits: 部分。delay 是两次使用之间的等待时间(秒),-1 表示只能使用一次:

YAML
kits:
  depart:
    delay: 86400
    items:
      - stonesword 1
      - stonepickaxe 1
      - bread 16

重新加载配置并授权该礼包:

终端
sudo mc-console 'essentials reload'
sudo mc-console 'lp group default permission set essentials.kits.depart true'

在聊天中显示等级

使用 EssentialsX Chat、Vault 和 LuckPerms 时,聊天格式在 config.yml 的 chat 部分设置:

YAML
chat:
  radius: 0
  format: '{DISPLAYNAME}&7:&r {MESSAGE}'

{DISPLAYNAME} 已包含 LuckPerms 的前缀和后缀。因此请勿再添加 {PREFIX},否则前缀会显示两次。radius: 0 会将消息发送给整个服务器。

使用 sudo mc-console 'essentials reload' 应用更改,然后在游戏中发送一条消息:应显示 LuckPerms 中设置的前缀。

管理经济

您可以在控制台中修改已连接过的玩家的余额:

终端
sudo mc-console 'eco give Steve 100'
sudo mc-console 'eco take Steve 25'
sudo mc-console 'balance Steve'

借助 Vault,其他兼容插件可以使用此经济系统。

验证结果

使用属于 default 组的非 OP 账户连接,然后尝试:

文本
/sethome maison
/home maison
/spawn
/kit tools
/balance

每条命令都应正常运行,不出现 You do not have access to that command 消息。如果您已启用 locale: zh,响应将以中文显示。

备份和更新

plugins/Essentials 文件夹包含配置、玩家数据和传送点:

终端
sudo tar -czf /opt/minecraft/backups/essentials-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server/plugins Essentials

请务必同时更新所有模块,因为它们的版本必须相同。对于开发构建:

终端
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
BASE="https://ci.ender.zone/job/EssentialsX/lastSuccessfulBuild"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
    FICHIER=$(curl -fsSL "$BASE/api/json?tree=artifacts%5BfileName%5D" | jq -r --arg m "$MODULE" '.artifacts[].fileName | select(startswith($m + "-"))')
    curl -fL -o "$FICHIER" "$BASE/artifact/jars/$FICHIER"
done
exit
sudo systemctl restart minecraft.service

故障排除

“You are running an unsupported server version!”

此版本的 EssentialsX 不支持您的 Minecraft 版本。请安装本指南开头表格中列出的构建。

“Version mismatch! Please update all Essentials jars to the same version”

各模块的版本不一致。请一起替换它们,然后重启服务器。使用 ls /opt/minecraft/server/plugins 确认同一模块没有残留两个文件。

“You do not have access to that command”

该玩家没有相应权限。请进行检查,例如针对 /home:

终端
sudo mc-console 'lp user Steve permission check essentials.home'

/r 使用 essentials.msg 权限,/spawn 需要 EssentialsX Spawn 模块。

“You cannot set more than 1 homes”

该玩家已达到上限。请授予其 essentials.sethome.multiple,并在需要时授予 essentials.sethome.multiple.vip 这样的级别。

“Detected supported permissions plugin LuckPerms without Vault installed”

Vault 缺失或未能加载。请确认它出现在 sudo mc-console plugins 的结果中,然后检查 sudo mc-console vault-info 的结果。

“The file is broken and Essentials can't open it”

某个 YAML 文件存在错误,通常是制表符或缩进不正确。日志会指明相关文件。请修正该文件或恢复备份,然后重启服务器。

其他插件的命令被替换

如果两个插件提供相同的命令,请使用完整形式,例如 /essentials:home。要让另一个插件永久优先,请将该命令添加到 config.yml 的 disabled-commands 中。

如需进一步了解,请查阅 EssentialsX 官方 Wiki。