快速開始

最後更新 2026-10-21

本頁說明如何安裝 go-scheduler、建立排程器、註冊第一個任務並優雅關閉。

前置需求

Go 1.23 或以上版本
非 Windows 平台：core.New 依賴 log/syslog，syslog 無法連線時改寫 stderr

安裝

使用 go get

go get github.com/pardnchiu/go-scheduler@latest

套件位於 core 子目錄：

import "github.com/pardnchiu/go-scheduler/core"

從原始碼

git clone https://github.com/pardnchiu/go-scheduler.git
cd go-scheduler
go build ./...
go test -race ./...

第一個任務

package main
import (
	"context"
	"log"
	"os/signal"
	"syscall"
	"github.com/pardnchiu/go-scheduler/core"
)
func main() {
	c, err := core.New(core.Config{})
	if err != nil {
		log.Fatal(err)
	}
	id, err := c.Add("@every 30s", func() {
		log.Println("heartbeat")
	}, "heartbeat")
	if err != nil {
		log.Fatal(err)
	}
	log.Println("task id:", id)
	c.Start()
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()
	<-ctx.Done()
	// 等待進行中任務結束
	<-c.Stop().Done()
}

步驟	呼叫	結果
1	`core.New(core.Config{})`	建立排程器，時區為 `time.Local`
2	`c.Add("@every 30s", ...)`	註冊任務並回傳遞增 ID；`@every` 最小間隔 30 秒
3	`c.Start()`	計算各任務下次觸發時間並啟動事件迴圈
4	`c.Stop().Done()`	停止排程，進行中任務結束後 context 被 cancel

go-scheduler 的定位

go-scheduler 是行程內（in-process）函式庫：匯入 core、在自己的 Go 程式中註冊任務，每個 action 都在該行程的 goroutine 中執行，不需要另外部署伺服器。

專案	型態	說明
robfig/cron	行程內 Go 函式庫	Go 的 cron 函式庫
go-co-op/gocron	行程內 Go 函式庫	流暢 API 風格的 Go cron 排程
reugn/go-quartz	行程內 Go 函式庫	極簡、零依賴的排程函式庫
adhocore/gronx	Go 函式庫與獨立 daemon	Cron 表達式解析器，並提供 task runner、job scheduler 與 daemon
madflojo/tasks	行程內 Go 函式庫	週期性任務的行程內排程器
ouqiang/gocron	自架服務	具 Web 管理介面的排程管理系統，由獨立的任務節點執行 shell 與 HTTP 任務
labulakalia/crocodile	自架服務	分散式任務排程系統，由調度中心透過 gRPC 呼叫 Worker 節點

在行程內函式庫這一類中，go-scheduler 把所有選項集中在一次 Add 呼叫：五欄位 Cron 表達式、描述符或 @every 間隔；以 []core.Wait 宣告前置任務，並對每個前置任務指定 Stop 或 Skip 策略；以及執行時限與逾時回呼。Stop 回傳的 context 會在無依賴的進行中任務結束後 cancel。

下一步

任務模型 — 任務欄位與狀態
排程語法 — Cron 欄位、描述符與 @every
設定 — 時區與單一任務選項
架構 — 事件迴圈、最小堆與 Worker 池
排程器 API — 完整簽章與錯誤條件