【后端接口】getsysvar 与 setsysvar：全局变量的读写与持久化

实战应用：用在哪里

全局变量是服务器的公共记事本：活动开关、世界 BOSS 状态、全服计数器全存这里。getsysvar 与 setsysvar 是读写对，setsysvarex 多一个落库参数，落与不落的选择就是重启后世界状态的分界线。

读写接口

---全局变量读写 varName:变量名 isSave:是否持久化
function getsysvar(varName) end
function setsysvar(varName, varValue) end
function setsysvarex(varName, varValue, isSave) end

-- 世界 BOSS 状态：落库保存
setsysvarex("world_boss_alive", 1, 1)
setsysvarex("world_boss_killer", "战神殿", 1)

-- 读取
local alive = getsysvar("world_boss_alive")

活动开关类变量必须落库（setsysvarex 置 1），重启后的世界状态靠落库变量恢复；临时计数类（当日已广播次数）不落库，重启归零反而符合预期。全局变量的读写没有锁，同一变量的并发写以末次写入为准，多触发点写同一变量的场景要设计好时序。

世界状态机

-- 世界 BOSS 的状态流转
function worldBossKill(killerName)
    setsysvarex("world_boss_alive", 0, 1)
    setsysvarex("world_boss_killer", killerName, 1)
    setsysvarex("world_boss_killtime", os.time(), 1)
    QF_Broadcast(killerName .. " 击杀了世界 BOSS")
    setontimerex(7700, 21600)  -- 6 小时后全局定时器触发刷新
end

世界 BOSS 的生死状态用三个落库变量描述：存活、击杀者、击杀时刻，重启后的世界状态从这三个变量完整恢复。全局定时器（setontimerex）配合落库变量完成刷新的延时调度，状态与调度是世界状态机的两条腿。全局变量的命名规范：模块前缀加下划线的命名让变量的归属一目了然，几十个全局变量的服务器的排查效率全靠命名纪律。

验证与监控

全局变量的写入清单与落库标记的审计，该落没落的变化会直接体现为重启后的状态丢失。

踩坑记录

全局变量的值曾经被存成 Lua 的布尔与 nil，落库序列化后读回变成字符串，变量的值域约定为字符串与整数两种是稳妥的实践。并发写的末次写入胜出语义在世界 BOSS 的归属判定上产生过争议，归属的判定改为先落独立的击杀流水再更新状态变量，状态是流水的结果而不是过程。

上线要点

全局变量的数量控制在两位数以内，超出的状态归类合并，记事本页数太多的服务器排查成本指数上升。读取频率高的全局变量在触发体里做局部缓存，变量写入时主动失效缓存。落库的写入频率与存档批量落盘的节奏配合，高频写的全局变量考虑合并字段减少写放大。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。