Yii命令行工具是框架原生能力，自定义命令须置于console/controllers/目录，类名以Controller结尾且命名空间匹配；参数分位置参数（方法参数）和命名参数（$this->options）；必须显式返回ExitCode常量，调试应使用$this->stdout()/$this->stderr()。
Yii 的命令行工具不是插件或额外包，而是框架原生能力，只要项目结构正确、yii 脚本可执行，就能立刻写和跑自定义命令。
自定义命令必须放在 console/controllers/ 目录下
Yii 2 不会自动扫描任意路径下的控制器。它只认 console/controllers/（注意是复数）这个固定目录，且控制器类名必须以 Controller 结尾，文件名需与类名严格一致（如 HelloController.php 对应 HelloController 类）。
- 错误做法：把控制器放在
commands/或console/Command/下——php yii hello会报错Unknown command "hello" - 命名必须用 PascalCase，不能是
hello-controller.php或hello_controller.php - 命名空间要匹配应用结构，典型的是
console\controllers，如果改了别名（如'controllerNamespace' => 'app\commands'），就得同步调整配置和目录
action 方法参数和 $this->options 的区别
Yii 控制台命令支持两种传参方式，但语义和用途完全不同：
- 方法参数（如
actionIndex($name = 'World')）接收的是「位置参数」，顺序敏感，不带--前缀，例如：php yii hello jack→$name = 'jack' -
$this->options是为支持命名参数（--env=prod）准备的，需在类中显式声明：public $env;，然后在方法里用$this->env访问；否则--env=prod会被忽略 - 混合使用时，位置参数优先于命名参数解析，比如
php yii hello --name=foo bar中，bar会赋给$name，而--name=foo被丢弃（除非你禁用默认行为）
退出码必须显式返回 ExitCode::OK 或 ExitCode::UNSPECIFIED
很多开发者直接用 echo 或 return;，结果命令看似跑完，但 shell 脚本里 $? 总是 0，掩盖真实失败状态。
- 正确做法：每个
action方法末尾返回ExitCode常量，例如：return ExitCode::OK;（成功）或return ExitCode::DATAERR;（数据错误） -
ExitCode定义在yii\console\ExitCode，常用值有OK、UNSPECIFIED、DATAERR、NOINPUT - 不返回值 ≠ 返回 0：PHP 函数默认返回
NULL，而 Yii 的基类会把它转成ExitCode::UNSPECIFIED（值为 1），这反而会让 CI 流水线误判失败
调试时别依赖 var_dump()，用 $this->stdout() 和 $this->stderr()
控制台命令没有 Web 环境的输出缓冲机制，直接 var_dump() 或 print_r() 可能被截断、格式错乱，甚至干扰管道操作（如 php yii mycmd | grep ...）。
-
$this->stdout("msg\n");输出到 stdout（可被重定向或管道） -
$this->stderr("error\n");输出到 stderr（适合报错，不影响正常输出流） - 避免裸
echo：它绕过 Yii 的输出控制，无法统一处理颜色、换行、编码等 - 调试复杂结构时，可用
$this->stdout(print_r($data, true) . "\n");，但上线前建议删掉
最常被跳过的细节是命名空间与目录的强绑定，以及退出码的显式返回——这两点不处理，命令在自动化脚本中就会变成“永远成功”的黑盒。
