一、常见原因分析

1. 时区设置问题

GitHub Actions 使用 UTC 时间，而不是本地时间。

YAML

# 错误示例on:schedule:-cron:'0 9 * * *'# 这是 UTC 9:00，而不是北京时间 9:00# 正确示例 (如果想在北京时间 9:00 运行)on:schedule:-cron:'0 1 * * *'# UTC+8 换算，要设置为 1:00

2. cron 语法错误

YAML

# ┌───────────── 分钟 (0 - 59)# │ ┌───────────── 小时 (0 - 23)# │ │ ┌───────────── 日期 (1 - 31)# │ │ │ ┌───────────── 月份 (1 - 12 或 JAN-DEC)# │ │ │ │ ┌───────────── 星期 (0 - 6 或 SUN-SAT)# │ │ │ │ │# * * * * *# 正确示例on:schedule:-cron:'30 1 * * *'# 每天 1:30 UTC-cron:'*/15 * * * *'# 每15分钟-cron:'0 */2 * * *'# 每2小时

3. 仓库状态检查

• 仓库必须是公开的，或者
• 如果是私有仓库，需要确保：
  • 没有超过 GitHub 的使用限制
  • 仓库处于活跃状态（没有归档）

二、调试和验证步骤

1. 添加手动触发选项进行测试

YAML

name:ScheduledTaskon:schedule:-cron:'30 1 * * *'workflow_dispatch:# 添加手动触发选项jobs:scheduled-job:runs-on:ubuntu-lateststeps:-name:Checktimerun:|
          echo "Current time: $(date)"
          echo "Current UTC time: $(date -u)"

2. 添加时间调试信息

YAML

jobs:debug-time:runs-on:ubuntu-lateststeps:-name:DebugTimeInforun:|
          echo "System time: $(date)"
          echo "UTC time: $(date -u)"
          echo "TZ: $TZ"
-name:TestSchedulerun:|echo"Scheduled task running at: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"

三、常见问题解决方案

1. 确保工作流文件正确放置

Code

你的仓库/
  └── .github/
      └── workflows/
          └── schedule.yml  # 工作流文件必须在这个位置

2. 优化定时任务配置

YAML

name:OptimizedScheduleon:schedule:-cron:'30 1 * * *'workflow_dispatch:# 手动触发选项jobs:scheduled-task:runs-on:ubuntu-latesttimeout-minutes:30# 添加超时限制steps:-uses:actions/checkout@v4-name:SetupEnvironmentrun:|
          echo "EXECUTION_TIME=$(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_ENV
-name:RunScheduledTaskrun:|
          echo "Task started at: ${{ env.EXECUTION_TIME }}"
          # 你的任务代码
-name:ErrorHandlingif:failure()run:|echo"Task failed at: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"

四、最佳实践建议

1. 使用合适的执行频率

YAML

# 推荐的定时设置on:schedule:-cron:'0 */6 * * *'# 每6小时执行一次-cron:'0 0 * * *'# 每天零点执行-cron:'0 0 * * MON'# 每周一执行

1. 添加状态检查

YAML

steps:-name:HealthCheckrun:|
      if [ -z "$GITHUB_TOKEN" ]; then
        echo "::warning::Token not found"
        exit 1
      fi

1. 设置通知

YAML

-name:SendNotificationif:always()uses:actions/github-script@v7with:script:|
            const message = `Scheduled task ${process.env.GITHUB_WORKFLOW} completed with status: ${process.env.GITHUB_JOB}`;
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'Scheduled Task Report',
              body: message
            });

五、故障排查清单

• 检查 cron 语法是否正确
• 验证时区换算是否准确
• 确认仓库权限和状态
• 检查 GitHub Actions 配额使用情况
• 验证工作流文件位置是否正确
• 测试手动触发是否正常工作

注意事项

1. GitHub Actions 的调度时间可能有 5-15 分钟的延迟
2. 过于频繁的调度可能会受到 GitHub 的限制
3. 私有仓库的定时任务有使用时间限制
4. 确保仓库没有被归档或禁用 Actions 功能

有用的调试命令

bash

# 检查当前时间
date -u

# 检查工作流状态
gh workflow list

# 查看运行日志
gh run list

希望这些解决方案能帮助您解决 GitHub Actions 定时任务不执行的问题。如果还有其他问题，欢迎继续询问。