symfony 7命令自动发现仅扫描src/command/精确路径，类名须含command后缀且文件名大小写敏感；setname()为硬性要求，命令名禁用空格；输出须用$output->writeln()；布尔选项需严格判true。
命令类必须放在 src/Command/ 目录下才能被自动发现
Symfony 7 默认启用命令自动发现，但只扫描 src/Command/ 这个**精确路径**。哪怕多一层子目录（如 src/Command/Dev/）或少一个字母（如 src/Commands/），命令就不会出现在 php bin/console list 中。
- ✅ 正确路径：
src/Command/BackupUsersCommand.php - ❌ 错误路径：
src/Console/BackupUsersCommand.php、src/Command/backupuserscommand.php（文件名大小写敏感）、src/Command/BackupUsers.php（类名没带Command后缀） - 自动发现不依赖
services.yaml配置 —— 即使你删掉所有console.commandtag，只要路径和命名合规，命令依然可用
configure() 里必须调用 setName()，且不能含空格
命令名是运行时唯一标识，Symfony 不校验格式，但 shell 解析会失败。比如 app:backup users 看似合理，实际执行时 users 会被当成下一个命令参数，导致 CommandNotFoundException。
- ✅ 推荐写法：
$this->setName('app:backup:users')或$this->setName('app:backup-users') - ❌ 绝对避免：
$this->setName('app:backup users')、$this->setName('app/backup/users') -
setName()是硬性要求 —— 即使只重写了execute()，没设名字也会报LogicException: The command defined in "..." cannot have an empty name.
execute() 必须返回 int，别用 echo 输出
返回值决定终端退出状态，影响脚本链式调用（如 &&）；而 echo 会绕过 Symfony 的输出格式化系统，导致颜色失效、测试断言失败、日志截断。
- ✅ 正确输出：
$output->writeln('✅ Backup completed.') - ❌ 错误输出：
echo '✅ Backup completed.'; - 返回码规范：
return Command::SUCCESS;（即0），失败用return 1;或return Command::FAILURE; - 若命令逻辑中抛出异常，Symfony 会自动捕获并转为非零退出码，无需手动
try/catch包裹整个execute()
选项读取要区分 VALUE_NONE 和默认值为 null
很多人以为 --force 选项未传入时是 false，其实它是 null。直接用 if (!$input->getOption('force')) 会导致逻辑翻车 —— 比如用户传了 --force=0（合法输入），结果也被判为未启用。
- ✅ 安全判断布尔选项：
if ($input->getOption('force') === true) - ✅ 读取带值选项（如
--limit=5）：$limit = $input->getOption('limit') ?: 10;，注意这里?:可用，因为null和false都触发默认 - ⚠️ 坑点：
addOption('verbose', 'v', InputOption::VALUE_NONE)声明后，--verbose和-v都生效，但--verbose=1会报错 ——VALUE_NONE不接受等号赋值
setName() 漏写、或把 echo 当成万能输出 —— 这些地方一错，命令就静默失效，连错误提示都不给你。
