直接用php artisan make:command生成命令类，Laravel 10默认自动发现，但需满足：类在app/Console/Commands目录、命名空间为App\Console\Commands、继承Illuminate\Console\Command；生成后必须运行php artisan list验证是否出现，否则签名、命名空间或文件末尾不可见字符可能出错。
直接用 php artisan make:command 就能创建，Laravel 10 默认自动发现命令，不用手动注册到 Kernel.php —— 但前提是类在 app/Console/Commands 目录下、命名空间正确、继承了 Illuminate\Console\Command。
怎么生成命令类并确认它能被识别
执行命令后必须立刻验证是否出现在 php artisan list 输出里，否则后续全白搭：
- 运行
php artisan make:command User:sync，生成app/Console/Commands/UserSyncCommand.php - 检查文件开头的命名空间是否为
namespace App\Console\Commands;（不是App\Commands或漏写） - 确认类继承自
Illuminate\Console\Command，且没有语法错误或 BOM 字符 - 执行
php artisan list | grep user:sync，有输出才算注册成功；没出现就先别写逻辑
签名定义和参数读取容易踩的坑
$signature 写错会导致 argument() 和 option() 拿不到值，甚至静默失败：
- 参数名只能含字母、数字、下划线：
{user_id?}✅，{user-id?}❌（会报Not enough arguments） - 布尔选项不要加等号：
{--force}✅，{--force=}❌（除非你明确需要接收字符串值） - 读参时别假设非空：
$userId = $this->argument('user_id');返回null而非空字符串，需显式判空 - 选项值类型要小心：
--force是true，--force=1是字符串"1"，不一致就崩
handle() 里调用模型或服务为什么报错
不是环境问题，是加载时机或写法问题。Artisan 命令启动时容器已就绪，但常见错误如下：
- 在
__construct()里直接 new 模型或调用未绑定的 Facade —— 改到handle()中再 resolve - 用了
User::all()处理大量数据 → 内存溢出，换成User::cursor()->each(...)或chunkById(500, ...) - 数据库操作没包事务：
DB::transaction()必须显式包裹多条写操作，不能依赖模型 save 自动开事务 - 忘了设默认连接：如果 config/database.php 的
'default'在当前环境（如 testing）不可用，会抛ConnectionException
怎么安全支持 --dry-run 模式
这不是 Laravel 内置功能，得自己加选项 + 分支判断，否则上线后误删数据没人兜底：
- 在
configure()或$signature里加：{--dry-run : 预览将执行的操作} - 在
handle()开头判断：if ($this->option('dry-run')) { $this->info('✅ 将更新 127 个用户状态'); return 0; } - 真实逻辑外层套一层条件，确保干跑时不触发任何写操作
- 别只打印“会删 X 条”，要具体到 where 条件和影响行数估算（比如
User::where(...)->count()）
最常被忽略的是命令类文件末尾的空白行或不可见字符 —— 它会让 PHP 解析失败，导致 php artisan list 不显示该命令，但又不报错。遇到“生成了却找不到”，先用 file -i app/Console/Commands/*.php 看编码，再用 tail -c1 app/Console/Commands/YourCommand.php | od -c 检查结尾有没有隐藏字节。
