【Lua实战】os.date 的格式化模板与活动时间键

实战应用：用在哪里

每日签到、每周任务、限时活动的时间键全靠 os.date 生成：%Y%m%d 的日键、%W 的周键、%H%M 的时刻判断。格式化字符的一字之差，就是跨天丢签到的客诉来源。

键的生成

---三类时间键：日、周、时刻
local dayKey = "Sign_" .. os.date("%Y%m%d")
local weekKey = "Week_" .. os.date("%Y%W")
local hourNow = tonumber(os.date("%H%M"))

---签到：日键的幂等标记
function Sign.daily(actor)
    if (getplayvar(actor, 2, dayKey) or "") ~= "" then
        sendmsg(actor, 1, "今日已签到")
        return false
    end
    setplayvar(actor, "HUMAN", dayKey, os.time(), 1)
    giveitem(actor, "签到礼包", 1)
    return true
end

三类键覆盖九成的时间业务：日键做签到的幂等、周键做行会周任务的进度、时刻串做活动开放窗口的判断。键里带年份与格式串的写死，跨年与跨月不会撞键——不带年的日键在 12 月 31 日与次年同月同日翻车的事故，一次就够记住。

格式字符的坑

---%W 与 %V：周的起点与首轮的归属不同
print(os.date("%Y-%m-%d %W", os.time({ year=2026, month=1, day=1 })))
print(os.date("%Y-%m-%d %V", os.time({ year=2026, month=1, day=1 })))

---%H%M 的字符串比较做开放窗口
local OPEN_WINDOWS = { { "1200", "1400" }, { "2000", "2200" } }
local function isOpen(now)
    local hm = os.date("%H%M", now)
    for _, w in ipairs(OPEN_WINDOWS) do
        if hm >= w[1] and hm <= w[2] then return true end
    end
    return false
end

格式字符的三个大坑：%W 与 %V 是两种周的定义（周日起算与 ISO 周一基准），周任务的键混用两种让跨周进度串门；%u 与 %w 的星期编号一个从周一起一个从周日算；跨平台对 %e（空格补零的日）的支持不一。开放窗口的判断用 %H%M 的四位数字符串直接比较，字符串序与时间序在补零格式下天然一致，比换算秒数少两步除法。时区的坑归 os.time 篇管，os.date 的本地化行为（月名星期的 locale）在中文服务器的键生成里要避开全拼格式，只用数字格式最稳。

验证与监控

时间键的单测覆盖边界：跨年、跨月、闰年 2 月 29、周日与周一的交界；键的冲突扫描进上线检查单，同键不同义的业务命名加前缀隔离。

踩坑记录

签到键曾经用 %m%d 没带年份，跨年的第一天全服玩家带着昨天的签到标记，键补年份后修复。周任务的 %W 曾经与客户端的周展示对不上，两端统一 %W 的定义并在文档注明周起点。开放窗口曾经用 %H 与 %M 分开比较，13:59 与 14:01 的边界判断写错方向，四位数合并比较后直观。

上线要点

时间键的生成集中在一个工具模块，业务不再各自拼串。键的命名规范：业务前缀加格式说明，键的可读性就是排障的速度。活动的时间配置表带预演功能：配置生效前打印未来三天的开放窗口，错配在上线前现形。

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