版本更新与公告
版本更新与公告
服务器完全启动后（控制台出现 Done 之后），插件会静默联网做一次检测：
- 读取官方版本号，与本地插件版本比对，不一致就在控制台提示去更新
- 读取公告文本，逐行打印到控制台
拥有管理员权限的玩家上线时，也会单独收到同样的提示。
为什么放在启动完成之后
检测挂在 Done 之后而不是插件加载阶段，有两个原因：
- 插件加载阶段服务器还在初始化世界、加载其他插件，此时做网络请求会拖慢启动
- 控制台在启动过程中刷屏严重，提示会被淹没；
Done之后打印，服主一眼就能看到
版本判定规则
只要本地版本与官方版本不完全一致就提示更新，不做大小比较。
| 本地版本 | 官方版本 | 是否提示 |
|---|---|---|
0.0.0 | 0.0.1 | 提示 |
0.0.1 | 0.0.1 | 不提示 |
0.0.2 | 0.0.1 | 提示 |
v1.0 | V1.0 | 不提示（忽略大小写） |
比较时会去掉首尾空白并忽略大小写差异。
配置
config.yml 的 UpdateChecker 一节：
UpdateChecker:
Enabled: true
Announcement: true
AdminPermission: snowygems.admin
NotifyAdminOnJoin: true
# 请不要修改下面的两个链接
VersionUrl: "https://raw.githubusercontent.com/SnowyMCT/SnowyGems-VersionCheck/main/version.txt"
AnnouncementUrl: "https://raw.githubusercontent.com/SnowyMCT/SnowyGems-VersionCheck/main/ann.txt"
Timeout: 8
| 字段 | 默认 | 说明 |
|---|---|---|
Enabled | true | 版本更新检测总开关 |
Announcement | true | 公告拉取总开关，可与更新检测分别关闭 |
AdminPermission | snowygems.admin | 哪个权限节点算「管理员」 |
NotifyAdminOnJoin | true | false = 只在控制台提示，不打扰任何玩家 |
VersionUrl | 官方源 | 版本号来源 |
AnnouncementUrl | 官方源 | 公告来源 |
Timeout | 8 | 连接与读取超时秒数，范围 1 ~ 60 |
Enabled 与 Announcement 同时为 false 时，启动检测整个跳过，不会有任何网络请求。
改完需要 /sgem reload。
完全关掉
UpdateChecker:
Enabled: false
Announcement: false
这样插件永远不会联网。适合内网服务器或不希望有任何出网行为的环境。
只想关掉玩家提示、保留控制台提示：
UpdateChecker:
NotifyAdminOnJoin: false
远端文件格式
如果你要自建版本源（比如给自己的分支用），格式如下。
version.txt：
version: 0.0.1
date: 2026年7月31日
version: 与 date: 都不区分大小写。只写一行纯版本号也能识别——解析不到 version: 时会把第一个非空行整体当作版本号。
ann.txt：纯文本，多行，每行原样作为一条公告展示，支持 & 颜色码。
&e欢迎使用 SnowyGems 先行版！
&7如果你有什么问题，请及时报告哦~
公告末尾的空行会被自动去掉。
提示文案自定义
全部文案在 lang.yml 的 update 节点，支持 & 颜色码与 title: / actionbar: / none: 前缀：
update:
# 控制台: 本地版本与官方不一致 占位符: {current} 当前版本 {latest} 官方版本 {date} 发布日期
console-available: "&e[SnowyGems] &f当前版本 &7{current} &f与官方 &a{latest} &7({date})&f 不一致, 请前往更新~"
# 控制台: 与官方一致 占位符: {current}
console-latest: "&8[SnowyGems] &7当前版本 &f{current} &7已是官方最新"
# 管理员上线: 本地版本与官方不一致 占位符: {current} {latest} {date}
player-available: "&e[SnowyGems] &f当前版本 &7{current} &f与官方 &a{latest} &7({date})&f 不一致, 请前往更新~"
# 公告展示的头尾装饰(公告正文来自远端 ann.txt, 每行原样显示)
announce-header: "&b&m &r &b&l公告 &b&m "
announce-footer: "&b&m "
lang.yml 是热重载的，改完保存即生效。
player-available 留着，然后设 Announcement: false（公告在控制台也不显示），或者把 announce-header / announce-footer 改成 none: 让装饰行消失。网络受限环境
联网走 JDK 自带的 HTTP，自动遵循服务端启动参数里的系统代理。插件不写死任何代理地址。
需要代理访问 GitHub 时，在启动脚本里加：
java -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=7890 \
-Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=7890 \
-jar paper.jar
或者干脆关掉检测（见上文）。
检测失败不会有任何报错，只在开启 Debug 且启用 Update tag 时记一行日志：
/sgem debug Update
日志会打印实际请求的 URL、HTTP 状态码、以及失败的异常类型。
常见问题
每次启动都要联网，会不会拖慢启动？
不会。检测在 Done 之后异步执行，且有超时保护（默认 8 秒）。启动流程完全不等它。
玩家上线会不会每次都重新联网？
不会。玩家上线提示复用启动时那一次的检测结果，不产生新的网络请求。
/sgem reload 会重新检测吗？
reload 只重读配置（URL、开关、超时等），不会重新发起检测。重新检测需要重启服务器。
控制台提示了新版本，但我确认自己是最新的？
对比一下 gradle.properties / JAR 文件名里的版本号与官方 version.txt 的内容，注意是否有多余空格或大小写差异之外的不同。判定是严格的字符串比较（去空白、忽略大小写）。
能不能改成每隔几小时检测一次？
当前版本只在启动时检测一次，没有定时轮询。设计上认为「服主重启服务器的频率」已经足够覆盖版本更新的节奏，定时联网收益不大。