Beego v2 的定时任务由内置 task 包提供,需导入 github.com/beego/beego/v2/task,使用 6 字段 crontab 表达式(含秒),且 task.StartTask() 必须在 beego.Run() 前调用。

beego 本身不内置独立的 Cron 模块,它的定时任务能力来自 task 包 —— 这是 Beego v2 的标准组件,不是第三方插件,也不需要额外 go get 安装。
你不需要“安装 Cron 模块”,只需要正确导入并初始化 task,它就支持类 crontab 的时间表达式(6 字段,含秒)。
确认你用的是 Beego v2
Beego v1 的 task 已废弃,且不兼容 v2 的 API。如果你执行过 go get github.com/astaxie/beego,那大概率拉的是旧版,会出错。
必须使用:
go get -u github.com/beego/beego/v2- 代码中导入路径必须是
github.com/beego/beego/v2/task,不是github.com/astaxie/beego/task - 项目里不能同时存在 v1 和 v2 的 import
task.NewTask 的 spec 格式容易写错
很多人复制 crontab 的 5 字段格式(分、时、日、月、周),但 beego/v2/task 要求 6 字段:秒 分 时 日 月 周 —— 第一位是秒,范围 0–59。
常见错误写法:
"0 0 * * *" → 缺少秒字段,运行时报 <code>invalid spec"* * * * * *" → 合法,但每秒执行一次,容易压垮服务"0 0 12 * * 0" → 每周日中午 12 点整执行(注意:周日是 0,不是 7)
task.StartTask() 必须在 beego.Run() 之前调用
这是最容易被忽略的启动顺序问题。如果先 beego.Run(),HTTP 服务已阻塞主线程,task.StartTask() 就 never 执行。
正确顺序示例:
func main() {
// 1. 初始化任务
tk := task.NewTask("daily-clean", "0 0 12 * * *", func(ctx context.Context) error {
fmt.Println("running daily cleanup")
return nil
})
task.AddTask("daily-clean", tk)
<pre class="brush:php;toolbar:false;">// 2. 启动任务调度器(关键!)
task.StartTask()
defer task.StopTask()
// 3. 最后才启动 Web 服务
beego.Run()}
漏掉 defer task.StopTask() 不会导致 immediate 错误,但在热重载或优雅退出时可能残留 goroutine。
调试时别只看日志输出,要查 task 是否真在跑
task 默认不打日志,即使函数 panic 也静默失败。建议加一层包装:
tk := task.NewTask("health-check", "0/30 * * * * *", func(ctx context.Context) error {
defer func() {
if r := recover(); r != nil {
beego.Error("task health-check panicked:", r)
}
}()
beego.Info("health-check running at", time.Now().Format(time.RFC3339))
return nil
})另外,task.ListTasks() 可以返回当前注册的所有任务名和状态,适合写个 admin 接口做核验。
Beego 的 task 模块轻量、无外部依赖,但对启动时机、spec 格式、错误捕获这三点非常敏感 —— 写错一个字符或调换两行代码,任务就“看似注册成功,实则从未触发”。


















