最稳妥的起点是用 php artisan make:command 生成命令类，否则因路径、继承或 $signature 格式错误会导致命令不显示；需确保类在 app/console/commands/、继承 illuminate\console\command、$signature 使用单引号且符合 dsl 规则。
直接用 php artisan make:command 生成命令类是最稳妥的起点，手动创建或放错路径大概率导致命令不出现、参数解析失败、依赖注入失效——不是 Laravel 不支持，而是它对类位置、继承关系和签名格式有硬性要求。
为什么新命令在 php artisan list 里不显示
常见原因就三个：类没放在 app/Console/Commands/ 目录下、没继承 Illuminate\Console\Command、或者 $signature 属性缺失或格式非法（比如含空格、以数字开头、用了中文括号）。
检查步骤：
- 确认文件路径是
app/Console/Commands/SendDailyReport.php，不是app/Commands/或app/Console/SendDailyReport.php - 打开文件，确认
class SendDailyReport extends Command，且顶部use Illuminate\Console\Command; - 确认有
protected $signature = 'report:daily';，不能写成protected $signature = "report:daily";（双引号在某些 PHP 版本下会触发变量解析） - Laravel 9+ 启用自动发现，但若你改过
composer.json的 PSR-4 配置或运行过composer install --optimize-autoloader，必须补跑composer dump-autoload - 改完代码后，务必执行
php artisan config:clear—— 自动发现机制依赖config/console.php缓存，缓存不清理，新增命令永远“看不见”
$signature 里参数和选项怎么写才不报错
$signature 是 Laravel 解析命令行输入的 DSL，不是自由字符串。写错一个符号，php artisan report:daily --help 就可能直接抛出 Symfony\Component\Console\Exception\LogicException。
关键规则：
- 必填参数：用
{user_id}，调用时必须传值，如php artisan report:daily 123 - 可选参数：用
{user_id?}，问号紧贴花括号，不能写成{user_id ?}或{user_id}? - 带默认值的可选参数：用
{user_id?=123}，值必须是字符串字面量，不能是变量或表达式 - 布尔选项：用
{--force}，用户执行--force时返回true，不传时返回null（不是false），判断请用$this->option('force') !== null - 带值的选项：用
{--limit=10}，等号必须紧贴选项名，不能写成{--limit =10}；传参时用--limit=5，不能用--limit 5 - 数组参数/选项：必须在
configure()方法中显式调用$this->acceptsMultipleValues()或->array()，否则只取第一个值
handle() 里读参和类型转换的坑
$this->argument() 和 $this->option() 返回的永远是字符串，哪怕你在 configure() 里写了 ->type('integer') —— 那只是影响帮助文档和输入校验，不自动转换类型。
典型翻车场景：
- 用
User::find($this->argument('id'))查不到记录？因为'123'和123在 Eloquent 的 casts 或 strict 模式下行为不同，应改为(int) $this->argument('id')或filter_var($val, FILTER_VALIDATE_INT) - 判断
--force是否启用时写if ($this->option('force'))，结果未传参时也进分支？因为null在布尔上下文中为false，但--force=0也会被当成字符串"0"，建议统一用$this->option('force') !== null - 想接收多个邮箱：
{email*}写法无效，必须在configure()中定义：$this->addArgument('email')->array()->description('收件人邮箱列表');，然后调用php artisan send:mail a@b.com c@d.com
命令返回值和信号处理容易被忽略
handle() 必须返回 int：0 表示成功，非 0 表示失败。返回字符串（如 return 'done'）会导致 Artisan 异常退出，且 shell 脚本无法正确判断状态。
另外，Artisan 命令默认不监听 SIGINT（Ctrl+C）。用户中断时 PHP 进程直接终止，数据库事务不会回滚、临时文件不会清理、锁不会释放。
安全做法：
- 所有耗时操作前注册信号处理器：
pcntl_signal(SIGINT, function () { $this->warn('收到中断信号，正在清理...'); // 清理逻辑 exit(130); }); pcntl_signal_dispatch(); - 涉及数据库写入时，手动包裹
DB::transaction()，并在catch或信号处理器中确保回滚 - 避免在
handle()中使用dd()，改用$this->comment(json_encode($data, JSON_UNESCAPED_UNICODE))，防止输出破坏终端样式或日志采集
