常见问题

玩家没有收到邮件

按以下顺序检查：

1. 确认模板文件已经放入模板目录，并且模板 id 与发送时填写的模板 ID 完全一致。
2. 执行 /lmail reload，确认控制台能够正常加载该模板。
3. 检查玩家是否在线，以及玩家数据是否已经加载完成。/lmail send 不能直接向离线玩家发送邮件。
4. 检查模板的 condition。任意一项条件不满足，邮件都不会进入玩家邮箱。
5. 如果模板启用了 only-mail: true，玩家曾经收到过相同模板后，将不能再次收到。
6. 检查模板是否仍处于定时发送时间范围内。

/lmail send 返回“发送成功”表示发送请求已经执行，不代表模板条件一定通过。实际写入邮箱前仍会检查唯一邮件限制和全部收件条件。

为什么不能向离线玩家发送邮件

/lmail send [玩家] [模板id] 只会查找在线玩家，并要求该玩家的数据已经加载完成。玩家离线或数据尚未加载时，指令会提示玩家不在线或数据未加载完毕。

需要向暂时离线的玩家发放活动邮件时，可以配置模板的定时发送时间。插件会在玩家数据可用后尝试自动发送，但玩家仍须满足模板条件，并且模板不能超过结束时间。

全服发送为什么有部分玩家没有收到

使用 /lmail send {online} [模板id] 时，只会遍历当前在线玩家。每名玩家仍会独立检查以下内容：

• 玩家数据是否已经加载。
• 模板是否启用 only-mail，以及玩家是否曾经收到过该模板。
• permission、nopermission 和 papi 条件是否全部满足。

因此，全服发送请求执行成功，不代表所有在线玩家都会收到邮件。

玩家在线但提示数据未加载

玩家数据会在加入服务器时读取。数据读取尚未结束、读取发生异常或数据库不可用时，可能暂时无法打开邮箱或接收邮件。

可以检查控制台中该玩家的数据读取日志。正常情况下会显示读取完成和邮件数量；发生异常时会显示读取失败并输出错误信息。

如果使用本地 YAML 存储，还应检查玩家数据文件是否损坏。如果使用 MySQL，则检查 LyMySQLCore 和数据库连接状态。

自动发送没有生效

检查以下项目：

检查项	说明
auto-send-time	自动发送检查间隔，单位为秒。应设置为大于 0 的合理数值。
timed-send-start-time	当前日期不能早于模板设置的开始日期。
timed-send-end-time	当前日期不能晚于模板设置的结束日期。
condition	玩家必须满足模板中的全部条件。
only-mail	启用后，曾经收到过该模板的玩家不会再次收到。
玩家数据	玩家数据必须已经成功加载。

除定时任务外，玩家上线或切换世界时也会触发相关邮件检查。

定时邮件为什么提前过期或没有继续发送

模板同时设置完整的 timed-send-start-time 和 timed-send-end-time 后，在该时间范围内收到的邮件会直接使用结束时间作为到期时间，而不是使用 expiration-time。

需要注意：

• 开始时间和结束时间按配置日期当天的 00:00:00 读取。
• 超过结束时间后，插件不会再通过该定时区间尝试发送。
• 玩家在时间范围内收到邮件后，该邮件会在配置的结束时间到期。
• 如果当前时间不在定时区间内，邮件到期时间才会按照 expiration-time 从收到邮件时开始计算。

修改模板后为什么没有生效

执行 /lmail reload 重新加载插件配置与邮件模板，并观察控制台中的模板加载信息。

默认的示例模板会在每次重载时被覆盖，而且示例文件明确标记为不能直接发送和打开。需要使用时，应复制示例模板并修改副本，不要直接编辑默认示例文件。

条件配置后所有玩家都收不到邮件

模板中的 condition 是逐项检查的。只要有一项返回不满足，发送就会停止。

支持的条件形式包括：

条件格式	作用
permission:{权限节点}	玩家必须拥有指定权限。
nopermission:{权限节点}	玩家必须没有指定权限。
papi:{表达式}	解析 PlaceholderAPI 变量并判断表达式。

如果同时配置互相冲突的条件，例如要求玩家既拥有又不拥有同一个权限，则任何玩家都无法通过检查。

PAPI 条件判断不正确

先确认 PlaceholderAPI 已经正常启动，并且表达式中使用的变量能够为该玩家返回有效内容。

数值表达式支持以下比较符：

运算符	含义
>=	大于或等于
>	大于
==	等于
!=	不等于
<	小于
<=	小于或等于

逻辑表达式还支持 && 和 ||。数值部分可以使用 +、-、*、/ 和括号。

字符串比较时，应为两侧字符串添加成对的单引号或双引号，例如：

condition:
  - "papi:{'%player_name%' == 'Steve'}"

如果变量返回的不是有效数字，却参与了大小比较或数学运算，条件计算可能失败。

only-mail 设置后为什么不能再次发送

only-mail: true 判断的是玩家是否曾经收到过该模板，而不是邮箱中是否仍保留该邮件。

玩家收到邮件时，插件会增加该模板的收件记录。即使邮件之后被领取、删除或过期，该记录仍然存在，因此玩家不能再次收到同一模板。

如果邮件需要重复发放，应将 only-mail 设置为 false。

/lmail try-send 为什么一直没有发送成功

/lmail try-send [玩家] [模板id] [次数] 会立即尝试一次；如果没有成功，再按每秒一次继续尝试，直到成功或达到指定次数。

持续失败时检查：

• 玩家是否保持在线。
• 玩家数据是否已经加载完成。
• 模板 ID 是否存在。
• 模板条件是否可能在重试期间变为满足。
• 玩家是否已经触发 only-mail 限制。

该指令不会绕过模板条件和唯一邮件限制。

邮件到期后为什么消失了

邮件达到 delete-time 后会被删除。插件会按照 auto-delete-time 设置的秒数定期扫描，玩家切换世界时也会执行一次过期检查。

删除时可以通过 message.mail-expire 向玩家显示过期提示。过期邮件被删除后，附件和领取指令不会执行。

邮件显示顺序不符合创建顺序

玩家邮箱中的邮件会按照到期时间排序，而不是按照模板文件名、模板 ID 或发送先后固定排序。到期时间更早的邮件会排在前面。

邮箱为什么无法打开

执行 /lmail open 后无法正常打开时，检查以下情况：

• 指令执行者必须是玩家，控制台不能打开玩家邮箱界面。
• 玩家数据必须已经加载完成。
• 插件不能处于重载状态。
• gui.title 和 GUI 物品配置必须能被当前服务端版本识别。

插件重载期间打开邮箱会被拒绝，数据未加载时也会直接提示错误。

邮箱翻页按钮没有反应

每页最多显示 27 封邮件。只有存在对应页内容时，上一页或下一页操作才会切换页面。

如果邮箱数量不足一页，下一页按钮不会产生页面变化。邮件领取或过期删除后，插件也可能自动返回上一页。

附件领取失败并提示空槽位不足

领取前，插件会统计玩家主背包前 36 个槽位中的空槽数量，并与模板的 need-slot 比较。

只要空槽数量小于 need-slot，本次领取就会停止，附件物品、领取指令和邮件删除都不会继续执行。

need-slot 是领取整封邮件前的统一检查值，不会根据实际成功生成的附件数量自动调整。请按邮件真实奖励需求设置，避免设置过大。

背包有空间，为什么仍提示空槽位不足

插件检查的是完全空置的槽位，不会计算已有物品堆叠后还能容纳多少数量。

例如，背包中已有未满的一组同类物品，但没有足够的完全空槽，仍可能无法通过 need-slot 检查。

点击领取后没有获得部分附件

邮件附件格式为：

物品库标识,物品ID,数量,是否给予

检查以下内容：

• 物品库标识是否正确。
• 对应物品库插件是否已经安装并正常加载。
• 物品 ID 是否存在。
• 数量是否为有效整数。
• 第四项是否为 true。设置为 false 时只用于展示，不会实际给予。

项目代码中可确认的物品库标识如下：

标识	对应物品库
mm	MythicMobs 旧版接口
mm5	MythicMobs 5.x 接口
ni	NeigeItems
si	SX-Item
af	AzureFlow
oa	OriginAttribute 物品接口
sx	SX-Attribute

如果物品库返回空物品，插件不会给予该项附件。领取流程仍可能继续执行其他附件、领取指令并删除邮件，因此配置前应确认物品 ID 可用。

附件配置为 false 后为什么只显示不发放

附件的第四项控制是否实际给予玩家：

items:
  - 'mm,邮件奖励,1,false'

设置为 false 时，该附件只用于邮箱中的奖励预览，不会加入玩家背包。这是正常行为。

领取成功后邮件为什么被删除

点击领取按钮并通过空槽检查后，插件会依次处理附件、执行 receive-commands，然后从玩家邮箱中删除该邮件。

邮件领取属于一次性操作。领取完成后不能再次打开或重复领取同一封邮件。

领取指令没有执行

检查模板中的 receive-commands 格式：

前缀	执行身份
[console]	控制台执行
[op]	玩家临时以 OP 身份执行
无前缀或 [player]	玩家身份执行

执行前会解析 PlaceholderAPI 变量。请确认：

• 指令内容不包含开头的 /。
• 目标指令所属插件已经加载。
• 变量能够正常解析。
• 指令前缀拼写正确。

代码会专门识别 [console] 和 [op]；其他情况按玩家身份执行，因此 [player] 会作为普通玩家指令前缀被移除的行为不能从现有代码确认。为避免问题，玩家身份指令建议直接填写指令内容，不添加前缀。

CDK 提示“无效 CDK”

可能原因包括：

• 输入的固定 CDK 与 CDK 组 ID 不一致。
• 随机 CDK 不存在于本地 cdkdata 文件或数据库 CDK 表中。
• CDK 组没有正常加载。
• 随机 CDK 尚未通过 /lmail createcdk 生成。
• MySQL 模式下数据库连接或 CDK 表查询失败。

固定 CDK 的实际兑换码就是 CDK 组 ID，不需要提前生成。

CDK 提示“该 CDK 已被使用”

随机 CDK 只能被一个玩家成功使用。兑换成功后，本地存储会把玩家名写入对应 CDK，MySQL 存储会把玩家名写入 CDK 表的 user 字段。

其他玩家再次兑换相同随机 CDK 时，会提示该 CDK 已被使用。

CDK 提示“你已兑换过该组 CDK”

每个 CDK 组对每名玩家只能成功兑换一次。

即使玩家改用同组的另一个随机 CDK，只要玩家的 cdk-logs 已记录该组 ID，仍然不能再次兑换。固定 CDK 同样受此限制。

CDK 一直提示兑换冷却中

每次执行 /lmail cdk [cdk] 都会记录一次兑换时间，包括输入无效 CDK 的情况。在 cdk-redeem-cd 设置的秒数内再次兑换，会触发冷却提示。

不要把 cdk-redeem-cd 设置得过短。CDK 查询和兑换在异步任务中处理，过短的间隔会增加服务器消耗和重复请求风险。

CDK 兑换成功但没有收到邮件

CDK 兑换与邮件写入是两个连续步骤。CDK 可以先被记录为已兑换，然后再调用邮件发送逻辑。

如果 CDK 组引用的邮件模板存在以下情况，玩家可能完成兑换但收不到邮件：

• 模板 ID 不存在。
• 玩家不满足模板 condition。
• 模板启用了 only-mail，玩家曾经收到过该模板。
• 玩家数据在处理期间不可用。

此时 CDK 已经被使用，玩家不能再次兑换。配置 CDK 前应先单独测试关联邮件能否正常发送。

CDK 邮件没发出，兑换消息或指令是否仍会执行

会。CDK 奖励流程会依次尝试发送 mail 中的邮件、发送 message 消息并执行 command 指令。

邮件发送失败不会自动撤销 CDK 使用记录，也不会阻止后续兑换消息和指令执行。

固定 CDK 为什么不能生成随机兑换码

fixed-cdk: true 表示该组使用固定 CDK，兑换码就是组 ID。对该组执行 /lmail createcdk 时不会生成随机 CDK，并会提示该组使用的是固定 CDK。

需要生成随机 CDK 时，应使用独立的 CDK 组，并设置：

fixed-cdk: false

随机 CDK 生成很慢

随机 CDK 会按 format 逐字符生成，并与已有 CDK 和本次生成结果进行查重。格式可产生的组合越少、已有 CDK 越多或单次生成数量越大，查重消耗越明显。

配置文件也明确提示不要大量生成和大量使用随机 CDK。应设置具有足够随机组合的格式，并控制单次生成数量。

本地存储模式适合群组服吗

本地模式会分别保存每台子服的玩家数据和 CDK 数据，服务器之间不会自动共享这些文件。玩家在不同子服操作时，可能出现邮箱、收件记录或 CDK 使用状态不一致。

项目指令帮助明确建议：本地存储只在主城等单一服务器使用邮箱功能。需要跨子服共享数据时，应使用 MySQL，并确保所有相关服务器连接同一数据库。

开启 MySQL 后功能没有生效

mysql.enable 的切换需要重启服务器，不能只执行 /lmail reload。

MySQL 模式必须满足以下条件：

1. 安装 LyMySQLCore。
2. LyMySQLCore 已成功连接数据库并能触发玩家安全加载、保存事件。
3. LyMailReload 的数据库地址、端口、数据库名、用户名和密码正确。
4. LyMailReload 控制台显示数据库连接成功，相关数据表已初始化。

只有安装 LyMySQLCore 且成功连接数据库后，MySQL 玩家数据与随机 CDK 存储功能才会生效。数据库连接失败时，应先修复连接问题，不要继续让玩家使用邮箱或兑换 CDK。

开启 MySQL 后需要哪些数据表

插件会尝试创建两个表：

表名	用途
LyMailReload	按玩家名保存序列化后的邮箱、收件记录和 CDK 记录。
LyMailReload_cdk	保存随机 CDK 的组 ID、兑换码和使用者。

实际表名前缀来自插件名称。数据库和表使用 utf8mb4 字符集与 utf8mb4_unicode_ci 排序规则。

MySQL 模式下玩家数据读取失败

检查控制台中的数据库连接、表初始化和玩家数据读取日志。常见检查项包括：

• LyMySQLCore 是否正常运行并连接数据库。
• mysql.enable 是否在重启前已经设置为 true。
• 数据库账号是否拥有查询、插入、更新和建表权限。
• LyMailReload 数据表是否存在。
• 数据库中的 data 字段是否包含可读取的 YAML 文本。

玩家数据未成功读取时，邮箱打开、邮件发送和 CDK 兑换都会受到影响。

本地玩家数据文件损坏怎么办

本地 YAML 模式会为玩家数据保存上一份稳定备份，备份文件后缀为 .bak。

读取主文件时，如果检测到 YAML 解析错误或 NUL 字符，插件会：

1. 输出玩家数据文件损坏警告。
2. 删除损坏的主文件。
3. 尝试读取对应的 .bak 备份。
4. 备份有效时，将备份恢复为主文件并继续加载。
5. 主文件和备份都不可用时，返回空数据。

保存过程会先写入唯一的临时文件，再切换备份并替换主文件，以降低写入中断导致数据损坏的风险。

数据目录出现 .tmp 或 .bak 文件是否正常

.bak 是玩家数据主文件的上一份稳定备份，用于主文件损坏后的自动恢复，不应随意删除。

.tmp 是保存过程使用的临时文件。正常保存结束后会被删除；插件读取数据时也会清理数据目录中遗留的 .tmp 文件。

修改 mysql.enable 后能否只重载插件

不能。默认配置明确说明数据库开关需要重启服务器。

插件启动时会根据 mysql.enable 注册 MySQL 或本地 YAML 的数据监听器。只执行 /lmail reload 不会重新切换已经注册的数据存储监听器。

邮件标题或界面颜色代码没有显示

插件会把配置中的 & 替换为 Minecraft 颜色符号。可在邮件标题、邮件内容、GUI 文本和消息配置中使用常规 & 颜色代码。

如果颜色没有生效，检查文本是否来自插件支持颜色替换的位置，并确认 YAML 引号和缩进正确。

GUI 物品显示成石头或图标不正确

GUI 按钮支持英文材质名以及旧版数字 ID 和子 ID 形式，例如 160:9。无法识别配置的材质时，部分 GUI 物品构建逻辑会回退为石头。

邮件模板的 icon 使用 Bukkit Material 名称。填写无法识别的名称时，已收到邮件的缓存图标会保留默认纸张物品。

建议按当前服务端版本使用有效材质名，并在修改后执行 /lmail reload。

PlaceholderAPI 没有安装会怎样

插件只会在检测到 PlaceholderAPI 已启用时注册 %lmail_...% 变量，但邮件条件与领取指令中也会调用 PlaceholderAPI 解析功能。

如果使用 PAPI 条件、PAPI 变量或插件提供的邮箱变量，应安装并正常启动 PlaceholderAPI。未安装时，相关变量和条件无法保证正常工作，并可能影响邮件发送或指令执行。

重载后邮箱暂时打不开

插件重载期间会阻止打开或刷新邮箱，并提示等待重载完成。重载结束后再执行 /lmail open。

如果重载完成后仍提示数据未加载，应检查玩家数据读取日志，而不是反复执行重载。