Go Cron 怎样为单个任务声明独立时区

我在一个服务里同时维护“按本地营业时间跑”和“按东京时间跑”的任务时，最容易犯的错是把整个 Cron 实例切到某个时区。这样一改，原本按服务器本地时间工作的任务也会一起移动。

更稳妥的做法是把时区当成调度表达式的一部分：在单个表达式前加 CRON_TZ=Asia/Tokyo。它只影响这条任务的时间解释，调度器的其它任务继续使用默认时区。

官方地址：https://pkg.go.dev/github.com/robfig/cron/v3

单任务独立时区的核心不是再创建一个 Cron，而是让这条表达式明确携带 IANA 时区；全局 WithLocation 负责默认值，CRON_TZ 负责局部覆盖。

先把它看成一种“局部覆盖”模式

robfig/cron/v3 默认用机器的 time.Local 解释计划。cron.New(cron.WithLocation(loc)) 可以改变整个调度器的默认区域，适合一组任务共享同一业务时区；但当只有一个任务属于另一个地区时，全局切换就会扩大影响面。

这时局部覆盖模式更合适：Cron 仍是一个共享的任务容器，默认时区仍然存在，只有带 CRON_TZ=Area/City 的表达式在自己的区域里计算。模式的价值是把“这个任务为什么按东京时间执行”写进任务定义，而不是藏在初始化顺序里。

典型实现：只给需要的任务加前缀

下面的例子让普通任务跟随调度器默认区域，让东京任务每天东京时间 04:30 触发。五字段表达式的第一个字段是分钟，因此这里不是 Quartz 风格的六字段写法。

package main

import (
    "log"

    "github.com/robfig/cron/v3"
)

func main() {
    // 共享一个调度器；未声明 CRON_TZ 的任务沿用它的默认时区。
    c := cron.New()

    // 普通任务示例：时间解释交给调度器默认区域。
    if _, err := c.AddFunc("0 9 * * *", func() {
        log.Println("执行本地上午任务")
    }); err != nil {
        log.Fatal(err)
    }

    // 局部覆盖：只让这一条任务按东京时间计算每天 04:30。
    if _, err := c.AddFunc("CRON_TZ=Asia/Tokyo 30 4 * * *", func() {
        log.Println("执行东京时间任务")
    }); err != nil {
        log.Fatal(err)
    }

    // 启动后继续保留同一 Cron 中两种时间解释方式。
    c.Start()
    defer c.Stop()
}

我更推荐把表达式和业务动作放在同一个小构造函数里：阅读者看到前缀就能判断时区，代码也不需要依赖“先调用某个 setter，再注册任务”的隐式约定。生产代码还应记录任务名和区域，方便从日志解释触发时间。

反例与代价：能写出来，不等于所有调度都适合

第一个反例是把 WithLocation 当成单任务配置。它改变的是默认解释区域，不是某一条表达式的私有设置；如果同一实例中有多个地区的任务，局部前缀更容易审查。

第二个反例是把 @every 24h 当作“每天某个城市的固定时刻”。固定间隔描述的是从加入或启动开始计算的周期，并不等价于墙上时钟；需要地区日历时应使用带 CRON_TZ 的 Cron 表达式。

还要接受夏令时的现实边界：官方文档提醒，发生“向前跳时”的日期里，某些计划时间可能不会执行。因此涉及扣款、结算、对账等不可重复业务时，不要只把 Cron 当唯一事实源，应让任务具备幂等键和补偿策略。

我的判断清单：什么时候用它

• 同一服务只有少数任务属于其它地区：优先使用 CRON_TZ=Area/City。
• 整组任务都属于一个业务区域：用 cron.WithLocation(loc) 设默认值，再按需要局部覆盖。
• 任务依赖“某地每天几点”：使用 Cron 表达式；任务只需要固定间隔：再考虑 @every。
• 区域字符串来自配置时，先用 time.LoadLocation 检查配置并在启动阶段处理错误，不要把未知区域留给运行时。

最后，v3 推荐 CRON_TZ；旧式 TZ=... 仍为兼容性保留。两者都应该使用 IANA 区域名，而不是随意写一个缩写时区。

相关问题

Go Cron 的所有任务都想用同一个时区怎么办？

在创建 Cron 时使用 cron.WithLocation(loc)，把它作为默认解释区域；只有例外任务再使用 CRON_TZ。

单任务时区前缀应该放在哪里？

放在完整表达式最前面，并与后面的五字段表达式用空格分开，例如 CRON_TZ=Asia/Tokyo 30 4 * * *。

为什么不为每个地区创建一个 Cron？

多个 Cron 不是错误，但会增加启动、停止、日志和任务清单的管理面。只有在生命周期、故障隔离或权限边界确实不同的时候，才值得拆开。