Linux crontab 定时任务不运行怎么办：从时间表达式到环境变量一步步排查

线上有个报表任务，每天 02:30 应该生成一份 CSV。第二天早上打开目录，文件没有出现；手动运行脚本却是正常的。这个场景很典型：crontab 看起来配置了，但实际到了时间没有得到结果。

遇到这种问题，先不要急着重写脚本。我们按“任务是否登记、时间是否命中、环境变量是否缺失、工作目录是否正确、日志是否可回查”的顺序走一遍，通常很快就能定位。

摘要

crontab 定时任务不运行，常见原因不是脚本本身坏了，而是运行环境和我们手动登录时不一样。稳定做法是使用绝对路径，显式声明必要环境变量，先切到工作目录，再把关键结果写入日志，并用一组小命令确认任务是否真的按预期触发。

适合人群

适合维护 Linux 服务器、定时脚本、报表任务、数据同步任务的开发和运维同学。文章用基础命令演示，不依赖特定发行版。

目录

• 问题现场：手动能跑，定时却没结果
• 第一步：确认任务有没有登记到正确用户
• 第二步：检查时间表达式和服务器时间
• 第三步：验证环境变量和工作目录
• 修复方案：把任务写成可回查的稳定版本
• 常见坑和最终检查

问题现场：手动能跑，定时却没结果

我们先把现象定清楚。假设脚本在命令行可以运行：

/usr/bin/python3 /data/report/jobs/daily_report.py

但放进 crontab 后，到了时间没有生成文件。第一轮猜测有三个：任务没登记到当前用户、时间表达式没触发、脚本依赖的环境和目录不对。

这一步先记录两个事实：手动运行结果正常，定时运行没有产物。只有把这两个状态区分开，后面才不会把脚本问题和调度问题混在一起。

第一步：确认任务有没有登记到正确用户

我们先看最容易忽略的一点：任务到底写在哪个用户下面。很多人用自己的账号测试脚本，却把任务写到了另一个账号里，或者反过来。

whoami
crontab -l

如果 `crontab -l` 里看不到任务，说明当前用户下并没有这条定时配置。此时不要继续猜脚本问题，先把任务登记到正确用户下。

再看任务内容是否有明显路径问题：

30 2 * * * /usr/bin/python3 /data/report/jobs/daily_report.py

这里用的是绝对路径。crontab 的运行环境很精简，不能默认它知道 `python3` 在哪里，也不能默认它从项目目录启动。

第二步：检查时间表达式和服务器时间

任务存在后，接着验证时间。比如 `30 2 * * *` 表示每天 02:30 触发。如果我们在 02:31 才写入配置，就要等到下一天，不会立刻补跑。

date
crontab -l

这一步要确认两件事：服务器当前时间是不是你以为的时区，表达式是不是确实覆盖了目标时间。为了快速验证，可以先用一分钟一次的临时任务做小测试，确认调度链路本身能触发。

* * * * * /bin/date

如果一分钟任务能触发，而日报任务不触发，就说明调度器本身不是主要问题，我们继续往脚本环境查。

第三步：验证环境变量和工作目录

现在来到最常见的原因：手动登录时有一堆环境变量，crontab 运行时却很干净。脚本里如果依赖相对路径、虚拟环境、配置文件路径，就可能手动正常、定时失败。

我们先把任务写得明确一点：

PATH=/usr/local/bin:/usr/bin:/bin
APP_ENV=prod

30 2 * * * cd /data/report && /usr/bin/python3 jobs/daily_report.py

这里做了三件事：声明 `PATH`，声明业务环境变量，先切到项目目录再运行脚本。这样脚本里的相对路径会以 `/data/report` 为基准，配置文件也更容易被找到。

如果脚本还依赖数据库地址、访问密钥或语言环境，也建议显式写在任务文件或脚本自己的配置读取逻辑中，不要只依赖登录会话里的临时变量。

修复方案：把任务写成可回查的稳定版本

现在可以整理一个更稳定的写法。关键不是把命令写长，而是让它具备三个能力：路径明确、环境明确、结果可回查。

PATH=/usr/local/bin:/usr/bin:/bin
APP_ENV=prod

30 2 * * * cd /data/report && /usr/bin/python3 jobs/daily_report.py > /data/report/logs/daily_report.log 2>&1

如果不想在 crontab 里写太多内容，也可以把环境准备放进一个启动脚本，再由 crontab 调用这个脚本。无论哪种方式，原则都一样：定时任务自己把运行条件交代清楚。

常见坑和最终检查

第一个坑是只写命令名，不写绝对路径。你在终端里能找到的命令，crontab 不一定能找到。

第二个坑是依赖相对路径。脚本里写 `config/app.yaml`，手动在项目目录里运行没问题，定时运行时工作目录变了就找不到。

第三个坑是没有日志。没有日志就只能猜，后面每次故障都会从头开始排。

最后可以按这组清单检查：

whoami
crontab -l
date
ls -lh /data/report/logs/daily_report.log

如果用户正确、任务存在、时间匹配、日志有新内容，基本就能确认调度链路已经恢复。再结合业务产物检查，例如报表文件是否生成，就可以收尾。

总结

Linux crontab 定时任务不运行时，排查顺序很重要。我们从现象出发，先确认任务登记，再确认时间表达式，然后把环境变量和工作目录补齐，最后让日志成为可回查证据。

稳定的定时任务有一个共同点：它不依赖“我登录进去时刚好有的环境”。路径、环境、目录、日志都写清楚，任务才能在凌晨无人值守时照样跑得稳。