注册自定义artisan命令需用php artisan make:command生成，确保类继承illuminate\console\command、定义$signature属性；laravel 9+支持自动发现，但需注意psr-4优化后须运行composer dump-autoload；参数用{name}、选项用--flag，签名错误或缓存未清将导致命令不可见或报错。
怎么注册一个自定义 Artisan 命令
Artisan 命令必须被 Laravel 在启动时发现并注册，否则 php artisan list 里根本不会出现它。最稳妥的方式是用 Laravel 自带的生成器，而不是手动新建文件再硬塞进 app/Console/Commands/ 目录后指望自动加载。
- 运行
php artisan make:command SendWeeklyReport，Laravel 会自动创建类、加到app/Console/Commands/、并在app/Console/Kernel.php的$commands数组里注册（Laravel 8+ 默认启用命令自动发现，但显式注册更可控） - 如果跳过生成器手写，务必确认类继承
Illuminate\Console\Command，且有protected $signature = 'report:weekly';属性——没这个，命令名就无效 - Laravel 9+ 默认启用「命令自动发现」，只要类在
app/Console/Commands/下、继承正确、有$signature，就能被识别；但一旦项目启用了 PSR-4 自动加载优化（如部署时用了composer install --optimize-autoloader），而你又没跑composer dump-autoload，新命令可能不生效
signature 里的参数和选项怎么写才不报错
$signature 不是自由格式字符串，它是 Laravel 解析命令行输入的 DSL。写错一个符号，php artisan report:weekly --help 就可能直接抛出 Symfony\Component\Console\Exception\LogicException。
- 必需参数：用
{name}，比如report:weekly {user_id}；访问时用$this->argument('user_id') - 可选参数：用
{name?}，注意问号紧贴花括号，不能写成{name ?}或{name}? - 带默认值的可选参数：用
{name?=123}，值必须是字符串字面量（数字也得写成'123'形式，不能是变量） - 选项（--flag 形式）：用
--force或--limit=5，对应$this->option('force')；布尔选项不要加等号，--force=true反而会被当成字符串值
常见错误：php artisan report:weekly --user-id=123 却在 signature 里写成 {user_id}（这是参数，不是选项），结果报 Not enough arguments。
命令里怎么安全地调用模型和队列
Artisan 命令运行在 CLI 环境，没有 HTTP 请求上下文，但模型和队列照样能用——前提是别踩环境和连接陷阱。
- 数据库连接默认复用
.env配置，但如果命令要长期运行（比如处理十万条记录），记得在循环里用DB::purge()或手动unset($model)，避免内存溢出 - 调用队列任务时，别直接 new 实例再 dispatch，优先用
dispatch(new SendEmailJob($data))；否则 Laravel 容器无法注入依赖，容易报Target class [App\Jobs\SendEmailJob] does not exist - 如果命令需要读取配置或缓存，确保在
handle()开头加config(['app.debug' => false])这类调整——CLI 默认不加载某些配置缓存，尤其是开发环境开启 debug 时，日志刷屏可能卡死进程
为什么本地能跑，上线后 command 找不到或报 Class not found
这基本不是代码问题，而是部署流程漏掉了关键 autoload 步骤。
- 检查
vendor/autoload.php是否被正确引入：Laravel 的artisan脚本第一行就是require __DIR__.'/vendor/autoload.php';，如果部署时删了vendor又没重装，必然失败 - 确认命令类的命名空间是
App\Console\Commands（Laravel 默认），且文件路径与命名空间严格匹配；改过命名空间？那就得手动在composer.json的"autoload": {"psr-4": {...}}里加映射，并运行composer dump-autoload - 有些 CI/CD 流程会执行
composer install --no-dev，但如果你的命令依赖了仅 dev 环境的包（比如spatie/laravel-ray），而命令里又写了ray()调用，就会在生产环境爆Class 'Ray' not found
最常被忽略的一点：修改完命令后，没清 config 缓存。哪怕只是改了 $signature，也要跑一次 php artisan config:clear，否则旧签名还缓存在 bootstrap/cache/config.php 里，命令列表不更新。
