CI4命令类必须继承BaseCommand并置于app/Commands/下，类名以Command结尾，需设置group和description，参数用getArgument()获取，输出用info()/error()方法，crontab调用须用绝对路径。
命令类必须继承 BaseCommand 且放在 app/Commands/ 下
CI4 的 CLI 命令不是独立脚本，不能直接 php mycommand.php 运行。所有自定义命令必须是 PHP 类，继承 CodeIgniter\CLI\BaseCommand，并严格放置在 app/Commands/ 目录下（子目录也允许，但需匹配命名空间）。
常见错误现象：Class 'ConfigServices' not found 或 Call to undefined method CodeIgniter\CLI\CLI::error()，本质是绕过 spark 入口，导致框架服务容器未初始化。
- 类名必须以
Command结尾（如ClearCacheCommand），否则spark list不识别 -
$this->group和$this->description必须设置，否则命令不会出现在spark list输出中 - 命名空间应为
App\Commands（或你配置的 PSR-4 前缀），文件路径与命名空间严格对应
参数和选项要用 $this->getArgument() 和 $this->getOption()
别再用 $argv 或全局变量解析输入——CI4 CLI 提供统一、类型安全的访问方式，且自动支持帮助提示（spark help app:clear-cache）。
示例：若定义了 protected $arguments = ['type' => '缓存类型']; 和 protected $options = ['--force' => '强制执行'];，则：
- 获取位置参数：
$this->getArgument('type')（返回字符串或 null） - 获取选项值：
$this->getOption('force')（返回 bool，有该 flag 就是 true） - 未声明的参数/选项会被忽略，不会报错但也不生效
注意：$this->getArgument(0) 这种数字索引写法不推荐，易出错；始终用键名访问更可靠。
输出必须用 $this->info() / $this->error()，不能用 echo
CI4 CLI 内置颜色、换行、进度条等能力，echo 会破坏格式一致性，且在管道或重定向场景下行为不可控（比如 cron 日志里乱码）。
-
$this->info('缓存已清空')→ 绿色文字 + 换行 -
$this->error('数据库连接失败')→ 红色文字 + 换行 -
$this->warn('跳过 config 缓存')→ 黄色文字 - 需要纯文本无样式输出？用
$this->write('raw text')
调试时如果发现输出没刷到终端，检查是否漏了换行符——$this->info() 自带，$this->write() 不带。
crontab 调用 spark 必须用绝对路径和显式 PHP 二进制
本地能跑的命令加进 crontab 就失败，90% 是环境差异问题：crontab 默认 PATH 极简，不加载 shell profile，工作目录也不是项目根目录。
正确写法只有一条路：
- 在 crontab 里写完整路径：
/usr/bin/php /var/www/myapp/spark app:clear-cache --force - 绝对禁止用
cd /var/www/myapp && php spark ...—— cron 不保证 shell 解释器一致，cd可能失效 - 确认
/usr/bin/php对应的 PHP 版本和扩展（pdo_mysql、openssl 等）与 Web 环境一致，运行php -m | grep pdo核对 - 务必重定向日志：
> /var/log/myapp-cron.log 2>&1，否则失败无声无息
最容易被忽略的是工作目录——spark 依赖当前目录下的 app/、writable/ 等路径，相对路径调用会让 APPPATH 指向错误位置，导致配置加载失败或日志写入权限错误。
