本文直击 Laravel 多租户场景下定时触发的数据库迁移（migrate:new）静默失败问题，揭示「cron 调用路径错误」这一高频陷阱，并提供从调度配置、命令健壮性到生产环境验证的全链路排查与加固方案。
本文直击 laravel 多租户场景下定时触发的数据库迁移（`migrate:new`）静默失败问题，揭示「cron 调用路径错误」这一高频陷阱，并提供从调度配置、命令健壮性到生产环境验证的全链路排查与加固方案。
在 Laravel 多租户 SaaS 应用中，通过定时任务自动为新租户执行数据库迁移（如 php artisan migrate:new）是常见实践。但正如您所遇——迁移在 cron 自动运行时“看似成功却实际跳过”，而手动执行却一切正常——这并非代码逻辑缺陷，而是调度执行环境与预期严重脱节所致。核心症结往往藏在最基础却最容易被忽略的一环：系统 cron 调用的不是目标环境的 artisan。
? 根本原因：Cron 执行路径错配（典型场景还原）
您提供的答案已精准定位：“cron job was executing php artisan schedule:run on staging application not production”。这意味着：
- 您的生产服务器上部署了 staging 和 production 两套 Laravel 应用（如 /var/www/myapp-staging 和 /var/www/myapp-prod）；
- 系统 crontab 中配置的行类似：
* * * * * cd /var/www/myapp-staging && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
- 而您的 MigrateNewTenant 命令仅注册在 production 的 app/Console/Kernel.php 中，staging 环境根本未定义该命令；
- 结果：schedule:run 每分钟在 staging 环境中执行 → 解析 Schedule::schedule() → 发现无 migrate:new 命令 → 静默跳过，不报错、不记录、不迁移。
✅ 验证方法：登录服务器，手动切换到 staging 目录，执行 php artisan list | grep "migrate:new" —— 若无输出，则确认命令缺失。
✅ 正确配置 Cron：路径、用户、PHP 三重锁定
确保 cron 100% 作用于生产环境，需显式声明所有关键路径：
# 推荐写法（生产环境专用） * * * * * cd /var/www/myapp-prod && /usr/bin/php artisan schedule:run >> /var/www/myapp-prod/storage/logs/schedule.log 2>&1
- cd /var/www/myapp-prod：绝对路径，强制进入生产项目根目录；
- /usr/bin/php：使用全路径 PHP，避免 cron 环境变量缺失导致 php 命令不可用；
- >> .../schedule.log 2>&1：将标准输出与错误重定向至日志，便于快速发现“Command 'migrate:new' is not defined”等关键提示。
⚠️ 注意：若使用 www-data 用户运行 cron，需确保该用户对 /var/www/myapp-prod 具有读取 .env、写入 storage/ 和执行 artisan 的权限（chown -R www-data:www-data /var/www/myapp-prod + chmod -R 755 storage/ bootstrap/cache/）。
?️ 增强 MigrateNewTenant 命令的健壮性
当前命令存在两个潜在风险点，建议立即优化：
1. 迁移前强制重载配置与连接
$this->call('migrate', [...]) 在非主连接上执行时，可能因配置缓存或连接复用导致状态混乱。应在每次切换租户后显式刷新：
// 在 foreach 循环内，$this->SwitchToTenantDB($tenant->db_name) 后添加：
config(['database.connections.tenant.database' => $tenant->db_name]);
DB::purge('tenant'); // 清除旧连接
DB::reconnect('tenant'); // 重建租户连接
2. 迁移失败时主动中断并记录
当前代码忽略 migrate 命令的返回值，失败也继续执行。应捕获结果并处理：
$result = $this->call('migrate', ['--force' => true, '--database' => 'tenant']);
if ($result !== 0) {
$this->error("Migration failed for tenant {$tenant->db_name}. Exit code: {$result}");
\Log::error("Tenant migration failed", [
'account_id' => $account_id,
'db_name' => $tenant->db_name,
'exit_code' => $result
]);
continue; // 跳过标记，留待人工干预
}
? 提示：--database=tenant 参数比依赖 config() 切换更可靠，前提是您的 database.php 中已正确定义 tenant 连接，并在 SwitchToTenantDB() 中完成动态配置。
? 生产环境验证清单（执行前必查）
| 检查项 | 验证方式 | 不通过后果 |
|---|---|---|
| ✅ Cron 是否指向 production 目录？ | crontab -l 查看路径；ls -la /var/www/myapp-prod 确认存在 | 调度器在错误环境运行，命令不可见 |
| ✅ migrate:new 是否在 production 的 Kernel.php 中注册？ | grep -r "MigrateNewTenant" /var/www/myapp-prod/app/Console/Kernel.php | 命令未注册 → schedule:run 完全忽略 |
| ✅ .env 中 APP_ENV=production 且 APP_DEBUG=false？ | cat /var/www/myapp-prod/.env \| grep APP_ENV | 环境误判可能导致配置加载异常 |
| ✅ storage/logs/schedule.log 是否有近期写入？ | tail -20 /var/www/myapp-prod/storage/logs/schedule.log | 无日志 → cron 未执行或权限拒绝 |
? 总结：定时任务稳定的黄金法则
- Laravel 的 schedule:run 本身不是守护进程，它只是一个“计划解析器”——必须由系统 cron 每分钟敲门一次，否则所有 ->command() 或 ->call() 都永不触发；
- 永远假设 cron 运行环境是“干净但贫瘠”的：无 shell profile、无别名、PATH 极简，因此所有路径（项目目录、PHP、artisan）必须绝对化；
- 多环境部署时，“一套 cron 配置打天下”是最大误区——staging 与 production 必须使用独立的 crontab 条目，或通过 APP_ENV 环境变量做硬隔离；
- 静默失败 = 日志缺失：将 >> /dev/null 替换为 >> schedule.log 2>&1 是诊断效率提升 10 倍的关键习惯。
修复后，您的租户迁移将真正实现“注册即就绪”，再无需手动救火。
