اگه تسکهای زمانبند (Scheduler) لاراول اجرا نمیشن، مشکل تقریباً همیشه تو یکی از این سه لایهست: خودِ cron daemon (نصب نیست، خاموشه یا crontab entry نداری)، مسیر اشتباه PHP یا artisan توی crontab، یا skip شدن بیصدای تسک بهخاطر mutex ی withoutOverlapping() یا timezone ناهماهنگ. قبل از هر تغییری، سه چک کوتاه بزن: php artisan schedule:list (آیا تسکها ثبت شدن؟)، crontab -l (آیا اصلاً cron entry داری؟) و php artisan schedule:run (آیا artisan دستی جواب میده؟). نکتهای که خیلی از توسعهدهندهها رو گیر میندازه اینه که لاراول وقتی تسک رو skip میکنه هیچ خطایی لاگ نمیکنه؛ حتی یه باگ تأییدشده تو Laravel 12.0 هم وجود داشت که تسکهای زیر دقیقه رو یکدرمیان رد میکرد (issue #57070). ادامهی مقاله دقیقاً نشون میده مشکل تو کدوم لایهست، کدوم لاگ رو باید بخونی و کی مشکل از خود لاراوله نه از تنظیمات تو.
چرا خطای Scheduler رو هیچجا نمیبینی؟
برخلاف خیلی از فریمورکها، Scheduler لاراول خودش daemon نیست. مستندات رسمی لاراول میگه فقط یه cron entry بذار که هر دقیقه php artisan schedule:run رو اجرا کنه و بقیهش با لاراوله (مستندات Task Scheduling). یعنی سه لایهی مستقل باید همزمان درست کار کنن:
- سیستمعامل: آیا cron daemon فعاله و entry واقعاً هر دقیقه اجرا میشه؟
- PHP binary: مسیر PHP درسته؟ extension ها لود میشن؟
- لاراول: تسکها توی
schedule:listدیده میشن؟ mutex یا timezone جلوشون رو نمیگیره؟
اگه هر کدوم از این لایهها خراب باشه، Scheduler کار نمیکنه ولی سیستمعامل و PHP هیچ خطایی نمیدن؛ همینه که دیباگش سخت میشه. جدول زیر پرتکرارترین سناریوها رو با نشونهی هر کدوم جمع کرده:
| سناریو | نشانه |
|---|---|
| crontab اصلاً نصب یا فعال نیست | هیچ لاگی از scheduler توی cron.log نیست |
| مسیر PHP یا artisan اشتباهه | No such file or directory توی لاگ |
| تسکها تو maintenance mode هستن | schedule:list نشونشون میده ولی اجرا نمیشن |
mutex ی withoutOverlapping هنوز expire نشده |
تسک یه بار اجرا میشه و بعد skip میشه |
timezone ناهماهنگ (سرور در برابر schedule_timezone) |
تسک سر ساعت اشتباه اجرا میشه یا اصلاً اجرا نمیشه |
باگ لاراول (مثل everyTenSeconds در Laravel 12.0) |
یه دقیقه کامل skip میشه |
| env-var از Docker به scheduler نمیرسه | config درست لود نمیشه |
پیشنیاز: قبل از شروع
این راهنما برای کسیه که با Laravel 10/11/12 کار میکنه، ساختار routes/console.php یا app/Console/Kernel.php رو میشناسه و حداقل یه تسک با Schedule::command(...) یا $schedule->command(...) تعریف کرده. اگه با کرون آشنایی نداری، اول آموزش crontab.guru یا man crontab رو ببین.
ماتریس محیط: VPS، cPanel و Docker چه فرقی دارن؟
اول بفهم رو کدوم سکویی، چون رفع مشکل تو هرکدون فرق داره:
| سکو | cron daemon | مسیر PHP معمول | کاربر cron | لاگ کجا بنویسم؟ |
|---|---|---|---|---|
| VPS Ubuntu | systemd با crontab -e یا /etc/cron.d/ |
/usr/bin/php یا نسخهی خاص مثل /usr/bin/php8.3 |
root یا www-data |
storage/logs/cron.log (پیشنهادی) |
| cPanel / DirectAdmin | daemon خود پنل | /usr/bin/php یا /usr/local/bin/php |
کاربر cPanel | لاگ داخلی پنل یا ~/logs/ |
| Docker (کانتینر جدا) | supercronic یا cron داخل کانتینر | /usr/local/bin/php (توی official php image) |
root (پیشفرض) | storage/logs/cron.log |
| Laravel Forge / Ploi | daemon خود پلتفرم | /usr/bin/php8.X |
کاربر پلتفرم | لاگ خود پلتفرم |
نکتهی کلیدی: مسیر PHP توی cron entry باید مطلق (absolute) باشه. اگه which php توی shell جواب میده ولی توی cron نه، یعنی PATH توی محیط cron فرق داره. همیشه مسیر کامل بنویس.
مرحله ۱: تشخیص با چهار دستور
قبل از هر تغییری، این چهار دستور رو پشتسرهم بزن؛ هرکدوم یه لایه رو چک میکنه:
# ۱. آیا تسکها توی لاراول ثبت شدن؟
php artisan schedule:list
# ۲. آیا crontab entry داری؟
crontab -l
# ۳. آیا artisan وقتی دستی اجرا میشه کار میکنه؟
php artisan schedule:run
# ۴. آیا خود cron daemon فعاله؟
systemctl status cron --no-pager
سه حالت اصلی رو تفکیک کن: اگه schedule:list خالیه، مشکل توی routes/console.php یا app/Console/Kernel.php ـه و تسکی اصلاً ثبت نشده. اگه لیست پرِه ولی schedule:run دستی هیچ خروجی مفیدی نمیده، مشکل توی خود artisan یا محیط اجراست. اگه schedule:run دستی درست کار میکنه ولی crontab entry نداری یا خروجی لاگت هیچیه، مشکل توی لایهی cron daemon ـه.
چرا skip شدن تسکها بیصده؟
از سورس رسمی Laravel 12.x (vendor/laravel/framework/src/Illuminate/Console/Scheduling/ScheduleRunCommand.php):
protected $signature = 'schedule:run {--whisper : Do not output message indicating that no jobs were ready to run}';
و از Event.php (خط ۱۴۶):
public function shouldSkipDueToOverlapping()
{
return $this->withoutOverlapping && ! $this->mutex->create($this);
}
یعنی وقتی تسک بهخاطر overlap رد میشه، لاراول استثنای صریح پرتاب نمیکنه؛ بیصدا ردش میکنه و چیزی توی لاگ نمینویسه. همینه که حس «همهچیز درست به نظر میرسه ولی تسک اجرا نمیشه» به وجود میاد.
مرحله ۲: رفع سریع
۲.۱ VPS Ubuntu
مستندات رسمی، همین قالب رو پیشنهاد میده (Running the Scheduler)؛ فقط مسیر PHP رو مطلق کن:
crontab -e -u www-data
* * * * * cd /var/www/your-project && /usr/bin/php8.3 artisan schedule:run >> /dev/null 2>&1
چهار نکتهی حیاتی:
cdقبل از artisan: لاراول برای پیدا کردن.envوvendor/به working directory نیاز داره.- مسیر مطلق PHP: خروجی
which phpتوی shell ممکنه با محیط cron فرق داشته باشه. >> /dev/null 2>&1: خروجی هر دقیقه رو بیصدا میکنه؛ اگه میخوای لاگ داشته باشی، بهجاش مسیر یه فایل لاگ رو بذار.- کاربر درست:
-u www-dataبرای وقتیه که PHP-FPM باwww-dataاجرا میشه؛ اگه با کاربر دیگهای deploy کردی، همون کاربر رو تنظیم کن.
بعد از ذخیره، ثبت شدن و فعال بودن cron رو چک کن:
crontab -l -u www-data
systemctl status cron
۲.۲ cPanel (بدون دسترسی root)
cPanel > Cron Jobs
Command: cd /home/username/public_html && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
Schedule: Once per minute (* * * * *)
مسیر PHP رو از MultiPHP Manager پنل پیدا کن؛ معمولاً /usr/bin/php یا /usr/local/bin/php ـه. اگه مسیر رو اشتباه بزنی، خطا معمولاً توی ایمیلی که پنل میفرسته میاد، نه توی لاگ سایت.
۲.۳ Docker (کانتینر جدا برای scheduler)
برای کانتینر، supercronic یه cron daemon سبک و مناسبه:
FROM alpine:3.19
RUN apk add --no-cache supercronic
COPY crontab /etc/crontab
CMD ["supercronic", "/etc/crontab"]
* * * * * cd /var/www && /usr/local/bin/php artisan schedule:run >> /var/www/storage/logs/cron.log 2>&1
نکتهی مهم Docker: کانتینر scheduler باید همون image اپ رو داشته باشه و همون volume رو mount کنه، وگرنه فایلهای artisan و .env رو نمیبینه. اگه env-var ها به scheduler نمیرسن، issue #46956 این سناریو رو دقیقاً گزارش کرده و مشکل معمولاً اینه که env-var فقط توی docker-compose تعریف شده؛ مقدار رو توی .env خود لاراول هم بنویس. اگه توی production از config:cache استفاده میکنی، این رفتار رو مقالهی چرا تغییرات .env در لاراول اعمال نمیشه کامل باز کرده.
مرحله ۳: رفع ریشهای
۳.۱ Timezone: سه لایه باید هماهنگ باشن
سه لایهی timezone رو یکییکی چک کن (خروجیها مثالن):
# ۱. timezone سرور
date
# خروجی مثال: Tue Aug 18 02:30:00 +0330 2026
# ۲. timezone PHP
php -r 'echo date_default_timezone_get()."\n";'
# خروجی مثال: Asia/Tehran
# ۳. timezone لاراول
php artisan tinker --execute="echo config('app.timezone').PHP_EOL;"
# خروجی مثال: Asia/Tehran
تنظیم توی .env:
APP_TIMEZONE=Asia/Tehran
و توی config/app.php. طبق مستندات رسمی، برای اینکه همهی تسکها با یه timezone واحد ارزیابی بشن، میتونی علاوه بر timezone گزینهی schedule_timezone رو هم تعریف کنی (Timezones):
'timezone' => 'UTC',
'schedule_timezone' => 'Asia/Tehran',
یا برای یه تسک خاص از متد timezone() استفاده کن:
Schedule::command('report:generate')
->timezone('Asia/Tehran')
->dailyAt('2:00');
دو نکته از مستندات رسمی و سورس:
- DST: بعضی timezone ها daylight saving دارن و موقع تغییر ساعت ممکنه تسک دوبار یا اصلاً اجرا نشه؛ مستندات لاراول توصیه میکنه تا حد ممکن از timezone scheduling جداگانه پرهیز کنی.
- ریاستارت cron: بعد از تغییر timezone سرور، سرویسها از جمله cron معمولاً باید ریاستارت بشن. maintainer لاراول (jbrooksuk) تو issue #49211 دقیقاً همین رو گفته: «تغییر timezone سرور معمولاً نیاز به ریاستارت سرویسهای مختلف داره و cron یکی از اونهاست.»
sudo systemctl restart cron
۳.۲ withoutOverlapping و mutex
وقتی withoutOverlapping() میزنی، لاراول با استفاده از cache یه قفل atomic میسازه. از سورس 12.x (ManagesAttributes.php):
public function withoutOverlapping($expiresAt = 1440)
{
$this->withoutOverlapping = true;
$this->expiresAt = $expiresAt;
return $this->skip(function () {
return $this->mutex->exists($this);
});
}
پیشفرض expiresAt طبق مستندات رسمی ۲۴ ساعته (Preventing Task Overlaps). یعنی اگه تسکی crash کنه و mutex پاک نشه، اجرای بعدیش تا ۲۴ ساعت skip میشه. برای پاک کردن این قفلها دستور php artisan schedule:clear-cache رو داری.
یه مثال زمانی (فرضی): تسکی که هر ۱۰ دقیقه باید اجرا بشه ولی ۱۵ دقیقه طول میکشه:
Schedule::command('slow:task')
->everyTenMinutes()
->withoutOverlapping(5); // قفل بعد از ۵ دقیقه expire میشه
00:00 تسک شروع میشه
00:10 cron میزنه schedule:run => mutex فعاله => skip
00:15 تسک اول تمام میشه
00:20 cron میزنه schedule:run => mutex هنوز فعاله => skip
00:25 قفل منقضی شده => تسک جدید شروع میشه
اشتباه رایج: کوتاه گرفتن expiresAt. اگه تسک معمولاً ۲۰ دقیقه طول میکشه و withoutOverlapping(10) بزنی، قفل قبل از تموم شدن تسک expire میشه و تسکهای موازی راه پیدا میکنن.
قاعدهی سرانگشتی: expiresAt رو حدوداً دو برابر حداکثر زمان اجرای تسک بذار. برای تسک ۵ دقیقهای، withoutOverlapping(10).
۳.۳ فرکانسهای زیر دقیقه و باگ Laravel 12.0
طبق مستندات، وقتی تسک زیر دقیقه (مثل everyTenSeconds()) تعریف میکنی، دستور schedule:run بهجای اینکه بلافاصله خارج بشه، تا آخر همون دقیقه زنده میمونه تا تسکهای زیر دقیقه تو کل دقیقه صدا زده بشن (Sub-Minute Scheduled Tasks). مستندات توصیه میکنه تسکهای زیر دقیقه یا job صف باشن یا با runInBackground() اجرا بشن، چون یه تسک کندِ زیر دقیقه، اجرای تسکهای بعدی رو هم عقب میندازه. موقع deploy هم دستور php artisan schedule:interrupt اجرای در جریان schedule:run رو قطع میکنه تا پروسهی قدیمی با کد جدید نجات نده.
روی همین رفتار، یه باگ هم تأیید شد: توی issue #57070 روی Laravel 12.0، تسکهای زیر دقیقه بهجای هر دقیقه، یکدرمیان اجرا میشدن (دقیقهی وسط کامل skip میشد). فیکس توی PR #59331 توسعه داده شد و اسفند ۱۴۰۴ (مارس ۲۰۲۶) به برنچ 13.x لاراول merge شد؛ قبل از آپگرید، changelog نسخهای که میخوای نصب کنی رو چک کن که فیکس داخلش باشه. تا اون موقع، اگه روی Laravel 12.0 هستی، بهجای فرکانسهای زیر دقیقه از فرکانسهای دقیقهای استفاده کن یا تسک رو با runInBackground() کوتاه و سبک کن.
۳.۴ schedule:work برای development
اگه نمیخوای هر دقیقه صبر کنی، روی سیستم خودت از schedule:work استفاده کن:
php artisan schedule:work
# یا با خروجی به فایل:
php artisan schedule:work --run-output-file=/tmp/schedule.log
از سورس رسمی (ScheduleWorkCommand.php):
protected $signature = 'schedule:work
{--run-output-file= : The file to direct <info>schedule:run</info> output to}
{--whisper : Do not output message indicating that no jobs were ready to run}';
این daemon هر ثانیه چک میکنه و فقط برای local development ـه؛ مستندات هم صراحتاً میگه روال معمول اینه که روی سرور production cron entry میذاری و از schedule:work استفاده نمیکنی.
جدول مرجع سریع: هر نشانه، یه علت
| نشانه | اولین چک | علت محتمل |
|---|---|---|
schedule:list خالیه |
routes/console.php رو باز کن |
Schedule اصلاً تعریف نشده |
schedule:run خطای Command not found |
artisan رو با مسیر مطلق اجرا کن | artisan تو PATH ی cron نیست |
| crontab entry هست ولی لاگ خالیه | systemctl status cron |
cron daemon خاموشه |
| تسک یه بار اجرا میشه و بعد skip | قفلهای cache رو چک کن | withoutOverlapping بدون expiresAt ی کافی |
| تسک سر ساعت اشتباه اجرا میشه | date و config('app.timezone') |
timezone ها هماهنگ نیستن |
| env-var تو Docker به scheduler نمیرسه | env رو تو کانتینر scheduler هم ست کن | issue #46956 |
| خطا با ایمیل از cPanel میاد | «MultiPHP Manager» رو ببین | مسیر PHP اشتباهه |
خطاهای رایج و رفع
خطا ۱: No scheduled commands are ready to run.
این خطا نیست؛ یعنی تسکها تو schedule:list هستن ولی الان نوبت هیچکدوم نیست. برای تست فوری، یه تسک هر-دقیقهای موقت بساز:
Schedule::command('inspire')->everyMinute();
php artisan schedule:run
اگه خروجی Inspiring چاپ شد، خود لاراول درست کار میکنه و مشکل تو لایهی cron ـه.
خطا ۲: Class "X" not found هنگام schedule:run
معمولاً بهخاطر composer install --no-dev توی production ـه که پکیجهای dev رو حذف کرده، یا autoload cache خرابه:
composer dump-autoload --optimize
php artisan config:clear
خطا ۳: تسک توی maintenance mode اجرا نمیشه
طبق مستندات، موقع php artisan down تسکهای زمانبندی اجرا نمیشن تا با نگهداری فعلی تداخل نکنن. اگه یه تسک حیاتی باید حتی تو maintenance اجرا بشه:
Schedule::command('critical:task')
->hourly()
->evenInMaintenanceMode();
خطا ۴: env-var های Docker به scheduler نمیرسن
issue #46956 تأییدشده: وقتی env-var رو فقط توی docker-compose ست میکنی، پروسهی scheduler ممکنه بهش دسترسی نداشته باشه. مقدار رو توی .env خود لاراول هم بنویس و بعد از تغییرات حواست به config:cache باشه.
ابزار خودمون: دیباگ سریعتر با Nyx
جمع کردن لاگ، crontab و خروجی دستورها وسط دیباگ حسابی کار داره. Nyx، دستیار هوشمند کاپیتان کد، میتونه اینها رو بهش بدی تا لاگت رو باهات مرور کنه و مرحلهی بعدی عیبیابی رو پیشنهاد بده؛ بهعلاوه مقالهی اجرای خودکار تست و دیپلوی با GitHub Actions نشون میده چطور میتونی schedule:run رو بهعنوان یه چک smoke تو CI اجرا کنی تا مشکلها قبل از رسیدن به سرور لو برن. اگه پروژهت صف هم داره، عیبیابی صف و Supervisor مکمل همین مقالهست.
سوالات متداول
۱. چرا تسکهام توی schedule:list هستن ولی اجرا نمیشن؟
معمولاً یکی از این سهتاست: crontab entry نداری، cron daemon خاموشه، یا mutex ی withoutOverlapping هنوز فعال ـه. چکلیست مرحله ۱ رو اجرا کن و اگه به mutex شک داری، php artisan schedule:clear-cache رو بزن.
۲. تفاوت schedule:run و schedule:work چیه؟
schedule:run یهبار اجرا میشه؛ همون کاری که cron هر دقیقه میکنه. schedule:work یه daemon ـه که هر ثانیه چک میکنه و فقط برای local development ـه، نه production.
۳. چطور بدون صبر کردن تست کنم؟
php artisan schedule:run
همون کاری رو میکنه که cron هر دقیقه میکنه. اگه این خروجی درست میده ولی cron اجراش نمیکنه، یعنی crontab entry نداری یا cron daemon خاموشه.
۴. چطور بفهمم cron اصلاً اجرا میشه؟
یه تسک تستی بساز که هر دقیقه توی یه فایل لاگ بنویسه:
Schedule::call(function () {
file_put_contents(storage_path('logs/cron-heartbeat.log'),
now().' scheduler is alive'.PHP_EOL, FILE_APPEND);
})->everyMinute();
بعد tail -f storage/logs/cron-heartbeat.log بزن؛ اگه هر دقیقه یه خط اضافه شد، cron زندهست.
۵. بدون SSH، تو cPanel چطور عیبیابی کنم؟
توی «Cron Jobs» از دکمهی Run Command استفاده کن؛ خروجی همونجا نمایش داده میشه. اگه خطا دیدی، مسیر PHP رو از «MultiPHP Manager» چک کن.
۶. Scheduler تو Laravel 11/12 چه فرقی با Laravel 10 داره؟
یکیدو تغییر ساختاری: تو Laravel 11 به بعد تسکها با facade ی Schedule توی routes/console.php تعریف میشن، نه توی app/Console/Kernel.php. هر دو syntax کار میکنن ولی ساختار جدید تو نسخههای جدید توصیه میشه. فرکانسهای زیر دقیقه هم از این نسخهها به بعد پشتیبانی کاملتری دارن، ولی حواست به رفتار schedule:run توی دقیقه باشه.
جمعبندی
عیبیابی Scheduler رو سهلایه انجام بده: اول مطمئن شو تسکها ثبت شدن (schedule:list)، بعد مطمئن شو cron daemon و entry درست هستن (crontab -l و systemctl status cron)، و آخر سراغ skip های بیصدای لاراول برو (mutex و timezone و فرکانسهای زیر دقیقه). بیشتر مواقع درست کردن مسیر PHP یا پاک کردن یه mutex قدیمی، کل مشکل رو حل میکنه.
اگه پروژهی لاراولیای داری که تسکهاش سر وقت اجرا نمیشن، از صفحهی تماس کاپیتان کد بگو تیم بررسیش کنه، یا قبلش با Nyx خودت شروع به دیباگ کن.