ThinkPHP 自定义命令行里 `execute` 方法死活不进断点：我以为是 Xdebug 抽风，结果是命令注册时 `command` 后缀少写了个字母
昨晚折腾到凌晨一点，起因是想写个定时清理过期日志的命令。代码看着挺规矩：继承 `BaseCommand`，写好 `configure` 设置名称和描述，`execute` 里放业务逻辑。结果 `php think` 列表里死活不显示我的命令，直接手动执行 `php think log:clear` 报 "Command is not defined"。
我第一反应是 Xdebug 没挂住，端口改来改去，IDE 配置重导了三遍，甚至怀疑 WSL2 网络又抽风。断点设在 `execute` 第一行，跑起来跟没设一样。后来干脆在 `configure` 里写 `die('到这里了')`，居然也没输出——这说明整个命令类就没被加载。
排查路径开始跑偏：先检查 `config/console.php` 的 `commands` 数组，我注册的 `app\command\LogClear` 明明在里面。又去看命名空间，去 `vendor/topthink/framework/src/think/console/Command.php` 翻源码，怀疑是不是 TP6 某版本改了命令发现机制。甚至把 `composer dump-autoload` 敲了五遍。
转机出现在我复制框架自带的 `make:command` 生成的示例命令时。对比发现，人家类名叫 `TestCommand`，我写的叫 `LogClearCommand`——等等，我的文件名是 `LogClear.php`，类名也是 `LogClear`。而 `configure` 里 `$this->setName('log:clear')` 这个名称，和类名其实没关系啊？
又绕了二十分钟，终于盯上 `config/console.php` 那行：
'log:clear' => 'app\command\LogClear',
问题根本不在配置。是我手滑，执行 `php think make:command LogClear` 时，TP 生成的文件末尾自动带了 `Command` 后缀，但我当时觉得冗余，手动把类名改成了 `LogClear`，文件名没改。而框架的命令发现机制在某些场景下（比如我后来手动改配置注册时），其实会尝试按约定后缀匹配。更坑的是，我后来自己写的新命令，类名是 `UserSyncCommand`，文件名 `UserSyncCommand.php`，配置里却写成了 `app\command\UserSync`——少了个 `Command` 后缀。
TP 的命令注册有两种路径：自动发现和手动配置。自动发现时框架扫 `app/command` 目录，按 `*Command.php` 规则匹配类名；手动配置时理论上你写啥类名就该加载啥。但实际运行时，如果类文件存在而类名对不上，或者反过来，报错信息统一是 "Command is not defined"，完全不告诉你到底是类找不到、还是类名不匹配、还是 `execute` 方法不存在。
我最后整理的排查 checklist：
1. 文件名、类名、配置里的字符串，三个地方逐字符对比，尤其注意 `Command` 后缀是否统一
2. 类必须继承 `think\console\Command`，抽象类或者接口实现都不行
3. `configure` 里 `setName` 只是命令调用名，和类名、配置键名可以不同，但建议保持一致减少混乱
4. 如果用了多应用模式，命令类放 `app/common/command` 还是 `app/index/command` 要看 `console.php` 的 `commands` 扫描路径
5. 最阴险的：OPcache 或者 runtime 里的命令缓存，改完代码执行 `php think clear` 再试
这次踩坑最大的教训是，断点不进的时候别先怀疑调试工具，先确认代码到底有没有被执行到。我在 Xdebug 上浪费了四十分钟，实际问题是类加载阶段就抛掉了，`execute` 根本轮不到。框架的报错信息在这种"类名对不上"的场景下太含糊，属于那种"你错得离谱反而没提示"的经典陷阱。
现在我的命令类全部强制 `Command` 后缀，配置用 `::class` 常量代替字符串，至少能少踩一类拼写坑：
UserSyncCommand::class 总比手敲 `'app\command\UserSync'` 靠谱点。
