创建控制器文件：在commands/目录下新建如hellocontroller.php的文件；2. 编写控制器代码：定义继承自yii\console\controller的类，并在其中创建以action开头的方法作为命令动作，使用stdout输出信息，返回exitcode常量表示执行结果，通过options()方法定义选项；3. 运行命令：在终端执行php yii / [参数] [--选项]，例如php yii hello/greet john或php yii hello/process --force=1 --env=prod。完整流程允许通过位置参数和选项灵活传递数据，结合prompt、confirm实现交互，配合日志、错误码、环境配置和定时任务使用，可构建健壮的后台自动化脚本。
Yii框架的CLI命令，说白了，就是让你能在命令行里直接跑Yii应用逻辑的一种方式。它通过一个入口脚本（通常是根目录下的
yii或
yii.bat）来执行，核心在于创建继承自
yii\console\Controller的控制器，并在其中定义你想要执行的“动作”方法。这种机制特别适合处理后台任务、数据迁移、定时脚本或者一些需要脱离Web环境运行的维护工作。
解决方案
要在Yii框架中创建控制台命令，你需要在项目的
commands目录下创建一个新的PHP文件，这个文件将作为你的控制台控制器。
具体步骤如下：
创建控制器文件： 在
commands/
目录下，新建一个文件，比如HelloController.php
。-
编写控制器代码： 在
HelloController.php
中，你需要定义一个类，它必须继承自yii\console\Controller
。在这个类里，你可以定义各种action
方法，每个action
方法就对应一个可以执行的命令。<?php namespace app\commands; use yii\console\Controller; use yii\console\ExitCode; /** * HelloController 演示如何创建和使用控制台命令。 */ class HelloController extends Controller { /** * 这是一个默认动作，当只输入 `php yii hello` 时执行。 * * @param string $message 要显示的消息，默认是 "Hello World!" * @return int Exit code */ public function actionIndex($message = 'Hello World!') { $this->stdout($message . "\n"); // 使用 stdout 输出到控制台 return ExitCode::OK; // 返回成功的退出码 } /** * 一个带参数的动作示例。 * * @param string $name 问候的对象名称 * @return int Exit code */ public function actionGreet($name) { $this->stdout("你好, " . $name . "!\n"); return ExitCode::OK; } /** * 一个带可选参数和选项的动作示例。 * * @param bool $force 是否强制执行 * @param string $env 运行环境 * @return int Exit code */ public function actionProcess($force = false, $env = 'dev') { if ($force) { $this->stdout("强制模式已启用。\n"); } $this->stdout("当前环境: " . $env . "\n"); $this->stdout("正在处理一些任务...\n"); return ExitCode::OK; } /** * 定义选项。 * 可以在这里为动作方法定义别名或默认值。 * 比如，为 actionProcess 定义 --force 和 --env 选项。 */ public function options($actionID) { return array_merge(parent::options($actionID), [ 'force', // 对应 actionProcess 的 $force 参数 'env', // 对应 actionProcess 的 $env 参数 ]); } } -
运行命令： 打开你的终端或命令行工具，进入到Yii项目的根目录，然后执行：
php yii hello
（会执行HelloController
的actionIndex
方法）php yii hello/index "自定义消息"
（显式执行actionIndex
并传递参数）php yii hello/greet John
（执行actionGreet
并传递John
作为参数）php yii hello/process --force=1 --env=prod
（执行actionProcess
并传递选项）
通过这种方式，你可以把各种复杂的逻辑封装成独立的命令行工具，非常方便。我个人觉得，当你需要跑一些耗时任务，或者需要自动化部署、数据清洗的时候，CLI命令简直是救星。
Yii CLI命令的命名约定与结构
Yii的CLI命令遵循一套相当直观的命名约定，一旦你掌握了，就能很快地定位和创建命令。
控制器命名： 你的控制台控制器文件通常放在
commands/
目录下。例如，一个名为HelloController.php
的文件，对应的命令前缀就是hello
。Yii会自动将驼峰命名的控制器类名（如HelloController
）转换为小写并用连字符分隔（hello
）。动作命名： 控制器类中的公共方法，如果以
action
开头，就会被识别为一个可执行的命令动作。例如，actionIndex()
对应index
动作，actionGreet()
对应greet
动作。actionIndex
是一个特殊的存在，它是每个控制器的默认动作，当你只指定控制器名而没有指定动作名时，就会执行它。-
命令结构： 完整的命令通常是
php yii <控制器ID>/<动作ID> [参数] [--选项]
。<控制器ID>
：对应你的控制器文件名（不含Controller.php
部分，且小写）。<动作ID>
：对应你的action
方法名（不含action
部分，且小写）。
模块内的命令： 如果你的应用使用了模块，并且想在模块内部定义CLI命令，你可以把它们放在模块的
commands/
目录下。比如，如果有一个blog
模块，你可以在modules/blog/commands/PostController.php
中定义命令。执行时，命令路径会变成php yii blog/post/create
，这让大型项目的命令管理变得井井有条。我发现这种分层管理对于避免命令冲突和保持代码清晰度非常有帮助。
如何在Yii CLI命令中处理参数和选项？
处理参数和选项是CLI命令的核心功能之一，它让你的命令变得灵活多变，能够根据不同的输入执行不同的逻辑。Yii在这方面做得相当不错。
-
位置参数 (Positional Arguments)： 这些参数是按照它们在命令中出现的顺序传递的。在你的
action
方法中，它们对应方法的参数。public function actionCreateUser($username, $email) { $this->stdout("创建用户: " . $username . ", 邮箱: " . $email . "\n"); }执行：
php yii user/create-user john john@example.com
如果参数有默认值，它们就变成了可选参数。public function actionDownload($url, $path = './downloads') { $this->stdout("下载 " . $url . " 到 " . $path . "\n"); }执行：
php yii file/download http://example.com/file.zip
或php yii file/download http://example.com/file.zip /var/tmp
-
选项 (Options)： 选项通常以双连字符
--
开头，用于提供非位置性的配置或标志。它们可以通过两种方式在Yii中处理：-
作为Action方法的参数： 最常见且推荐的方式。
public function actionProcessData($dryRun = false, $batchSize = 100) { if ($dryRun) { $this->stdout("正在以空运行模式处理数据。\n"); } $this->stdout("批处理大小: " . $batchSize . "\n"); }执行：
php yii data/process-data --dry-run=1 --batch-size=50
Yii会自动将--dry-run=1
解析为$dryRun = true
，--batch-size=50
解析为$batchSize = 50
。布尔类型的选项，只要出现，无论值是什么（1
,true
,on
等），都会被视为true
。 -
通过
options()
方法定义公共属性： 这种方式允许你为选项定义别名或更复杂的解析规则。 在你的控制器中，重写options()
方法：class MyController extends Controller { public $verbose = false; // 定义一个公共属性作为选项 public function options($actionID) { // 返回当前动作可用的选项列表 return ['verbose']; // 对应 --verbose } public function actionDoSomething() { if ($this->verbose) { $this->stdout("详细模式已启用。\n"); } $this->stdout("正在做一些事情...\n"); } }执行：
php yii my/do-something --verbose
-
-
交互式输入与输出： 在CLI命令中，你经常需要与用户进行交互，比如提示用户输入、确认操作。Yii提供了一些方便的方法：
$this->stdout($string)
：向标准输出（通常是控制台）打印字符串。$this->stderr($string)
：向标准错误输出打印字符串，适合打印错误信息。$this->prompt($text, $options = [])
：提示用户输入，并返回输入的内容。$this->confirm($message, $default = false)
：提示用户确认（Y/N），返回布尔值。public function actionDeleteData() { if ($this->confirm('确定要删除所有数据吗？这不可逆！')) { $this->stdout("数据已删除。\n"); } else { $this->stdout("操作已取消。\n"); } }这些工具让CLI命令的交互性大大增强，尤其是在执行一些高风险操作前，加一个确认步骤是必不可少的。
Yii CLI命令的实用技巧与常见问题
在实际开发中，CLI命令虽然方便，但也有些地方需要注意，以及一些小技巧能让你的工作更顺畅。
环境配置： CLI命令默认运行在
console
应用配置下，它可能与你的Web应用配置有所不同。确保数据库连接、组件配置等在CLI环境下是正确的。我记得有次调试一个CLI脚本，怎么跑都不对，最后发现是环境配置没弄好，数据库连接指向了错误的测试库，简直抓狂。检查console/config/main.php
和console/config/params.php
这些文件非常重要。日志记录： CLI命令通常是无人值守运行的，因此良好的日志记录至关重要。Yii的日志组件在CLI环境下同样可用。你可以配置日志目标，将CLI命令的输出、错误和调试信息记录到文件中，而不是仅仅打印到控制台。这样，即使命令跑出问题，你也能通过日志文件追溯原因。
定时任务 (Cron Jobs)： 许多CLI命令都是设计来作为定时任务运行的。在Linux系统上，你可以使用
crontab
来设置。 比如，每天凌晨3点执行一个数据清理命令：0 3 * * * /usr/bin/php /path/to/your/yii/app/yii data/cleanup > /var/log/myapp_cleanup.log 2>&1
注意这里的php
路径和Yii应用根目录的路径。将输出重定向到日志文件是个好习惯，避免标准输出填满你的系统邮箱。内存与执行时间限制： CLI脚本通常处理大量数据或执行耗时操作，可能会遇到PHP的内存限制（
memory_limit
）或最大执行时间（max_execution_time
）。你可以在脚本开头通过ini_set()
来临时调整这些限制，或者在php.ini
中为CLI环境单独配置。错误处理与退出码： CLI命令应该返回一个退出码（Exit Code），通常
0
表示成功，非0
表示失败。这对于自动化脚本判断命令执行结果非常有用。Yii提供了yii\console\ExitCode
常量，比如ExitCode::OK
和ExitCode::UNSPECIFIED_ERROR
，让你的退出码更具语义。依赖注入与服务定位器： 在CLI命令中，你可以像在Web应用中一样，通过
Yii::$app->componentName
来访问应用程序组件，比如数据库连接、缓存、邮件发送器等。这保证了CLI命令与Web应用共享相同的业务逻辑和基础设施。安全性： 虽然CLI命令通常只在服务器上由受信任的用户或系统执行，但仍然需要注意安全。避免在CLI命令中硬编码敏感信息，并确保只有授权用户才能执行关键命令。例如，一个删除数据的命令，最好加上确认提示或者只允许特定环境执行。
这些细节和技巧，是我在实际开发中慢慢摸索出来的，它们能帮助你写出更健壮、更易于维护的Yii CLI命令。
