Artisan命令的handle方法不必强制返回int，但强烈建议返回整数退出码；应校验参数选项、优先使用Eloquent模型、统一用$this->line()等方法输出。
Artisan命令的handle方法必须返回int吗？
不是必须，但强烈建议返回int。Laravel底层用symfony/console，其Command::run()期望返回整数退出码。不显式返回值时PHP默认返回NULL，会被转为0（成功），但容易掩盖逻辑错误。实际运行中若handle()抛出异常，Laravel会自动转为非零退出码；但主动控制更可靠。
-
return 0;表示成功（标准POSIX约定） -
return 1;或其他非零值表示失败（如数据校验不通过、外部服务不可用） - 避免返回
string或bool，会导致PHP警告且退出码不可控
handle方法里怎么安全访问参数和选项？
别直接读$this->argument('name')或$this->option('force')前不校验——Laravel不会自动验证参数是否传入，空值或缺失时返回null或空字符串，容易引发UndefinedArrayKey或逻辑错乱。
public function handle()
{
$userId = $this->argument('user-id');
if (! is_numeric($userId)) {
$this->error('user-id must be a number');
return 1;
}
$batchSize = $this->option('batch') ?? 100;
if ($batchSize < 1 || $batchSize > 5000) {
$this->warn('Invalid --batch value, using default 100');
$batchSize = 100;
}
// ... 执行逻辑
return 0;
}
- 参数名、选项名必须和
configure()中定义的addArgument()/addOption()完全一致（包括连字符） - 使用
??提供默认值比optional()更直观，尤其对选项 - 用
$this->error()/$this->warn()而非echo，确保输出被Artisan正确捕获和着色
handle里调用Eloquent模型要注意什么？
Artisan命令默认在console环境运行，但数据库连接、队列驱动、缓存配置可能和web不同。常见坑是：本地开发用SQLite内存库，线上用MySQL，而命令里硬编码了DB::table()写法，导致迁移失败或数据错乱。
- 优先用Eloquent模型，它自动走当前环境配置的连接（
config('database.default')） - 避免在
handle()开头就DB::beginTransaction()——如果命令被Ctrl+C中断，事务不会自动回滚；改用DB::transaction()闭包 - 大量数据处理时，用
chunkById()代替get()，防止内存溢出：User::where('active', 1)->chunkById(100, fn ($users) => { ... })
为什么handle执行完没输出，或者输出顺序错乱？
Artisan命令输出被Symfony的OutputInterface缓冲，但如果你在handle()里混用了echo、var_dump()或日志门面（Log::info()），输出会脱离Artisan控制流，导致：
- 进度条（
$this->output->progressStart()）被echo打断 - JSON格式输出（如
--json选项）混入调试内容，解析失败 - CI/CD流水线里因非零退出码误判失败（比如
var_dump()输出到stderr）
统一用$this->line()、$this->table()、$this->withProgressBar()等方法。调试时用$this->comment('debug: '.$value)，上线前删掉——别留dd()或dump()。
