laravel自定义artisan命令需满足：类继承command、置于app/console/commands/、命名规范；laravel 8+自动发现但依赖config缓存，需php artisan config:clear；参数选项始终返回字符串，须手动类型转换；耗时操作应手动处理sigint信号；tinker中调用需注意cli环境隔离。
如何生成并注册一个可运行的自定义 Artisan 命令
Laravel 的 php artisan make:command 是起点，但生成后必须手动注册（Laravel 8+ 默认自动发现，但需满足命名与目录约束）。若命令未出现在 php artisan list 中，大概率是没被加载。
确保命令类继承 Illuminate\Console\Command，且位于 app/Console/Commands/ 目录下；类名需符合 PSR-4（如 SendMonthlyReport），文件名必须匹配（SendMonthlyReport.php）；Laravel 8+ 会自动扫描该目录下的命令，无需在 app/Console/Kernel.php 的 $commands 数组中重复添加——除非你把它放到了别处。
- 如果用了自定义命名空间（比如
App\Console\Commands\Reports\），必须显式在Kernel.php的$commands中注册全限定类名 - 运行
php artisan config:clear后再试 —— 自动发现依赖config/console.php的缓存，改了目录结构不清理缓存会导致命令“消失” - 检查
signature属性：不能含空格、不能以数字开头、推荐用冒号分隔（如report:send），否则artisan解析失败且无明确报错
如何正确解析参数和选项并避免类型陷阱
$this->argument() 和 $this->option() 返回的永远是字符串，哪怕你在 configure() 中声明了 ->type('integer') 或 ->boolean() —— 这些只影响帮助文档显示和输入校验，不自动转换类型。
常见翻车点：想用 $this->argument('id') 当整数传给 Eloquent 查询，结果查出空集，因为 User::find('123') 和 User::find(123) 在严格模式下行为不同（尤其配合 casts 时）。
- 手动强转：用
(int) $this->argument('id')或filter_var($val, FILTER_VALIDATE_INT) - 布尔选项（
--force）默认返回null（未传参时），不是false；判断请用$this->option('force') !== null，而非empty()或直接布尔上下文 - 数组型参数（
*args）需在configure()中显式调用->array()，否则只取第一个值
如何在命令中安全执行耗时操作并响应中断
Artisan 命令默认不具备信号监听能力。用户按 Ctrl+C 时，PHP 进程直接终止，可能留下脏数据或锁文件。
Laravel 不提供开箱即用的信号处理，但可通过 pcntl_signal() 手动挂接。注意：仅 CLI SAPI 支持，且需启用 pcntl 扩展（Docker 镜像常默认禁用）。
- 在
handle()开头加pcntl_async_signals(true)（PHP 7.1+） - 注册
pcntl_signal(SIGINT, [$this, 'handleSigint'])，并在回调中调用$this->warn('Received SIGINT, cleaning up...')+ 手动释放资源 - 每轮循环后加
pcntl_signal_dispatch()，否则信号可能延迟触发甚至丢失 - 更稳妥的做法是避免长循环，改用队列（
dispatch(new ProcessBatchJob(...))）+ 超时控制（--timeout=300）
为什么 php artisan tinker 里调用命令会失败
在 Tinker 中用 Artisan::call('report:send') 看似合理，但容易忽略上下文隔离问题：Tinker 是交互式 REPL，而 Artisan 命令默认依赖完整的请求生命周期（如数据库连接、配置加载、事件调度器）。某些命令在 Tinker 中静默失败，是因为其 handle() 抛了异常但被 Artisan::call() 吞掉，只返回退出码。
- 调试时优先用
php artisan report:send --verbose，而非 Tinker - 若必须在 Tinker 中触发，加
try/catch并打印$e->getTraceAsString() - 避免在命令中直接访问
request()或session()—— 它们在 CLI 下不可用，Tinker 里更不存在
if (app()->runningInConsole()) 判断，有时比重构整个流程更有效。 
