在 configure() 中用 $this->addOption() 添加自定义选项，handle() 中必须用 $this->option('name') 安全读取；--env 不透传，短选项不支持连写 -vf，类型语义（VALUE_NONE/REQUIRED/OPTIONAL）须严格匹配。
Artisan 命令怎么加自定义选项（--flag 或 -f）
直接在 configure() 里用 $this->addOption()，不是靠构造函数或属性注入。Laravel 不会自动把命令行参数映射到属性，必须显式声明并手动取值。
常见错误是写了 --env=local 却在 handle() 里直接用 $this->env —— 这个属性根本不存在，Laravel 不做魔术赋值。
-
$this->addOption('force', 'f', InputOption::VALUE_NONE)：布尔开关，不带值，php artisan foo --force或-f -
$this->addOption('timeout', 't', InputOption::VALUE_REQUIRED, '30')：必填值，--timeout=60或-t 60 -
$this->addOption('log-level', null, InputOption::VALUE_OPTIONAL, 'info')：可选值，--log-level=debug或单独写--log-level（用默认值）
在 handle() 里怎么安全读取选项值
一律用 $this->option('xxx')，别用 $this->input->getOption('xxx') —— 虽然底层一样，但前者是 Laravel 封装后的推荐方式，且对空字符串、null 的处理更一致。
容易踩的坑：当选项类型是 VALUE_OPTIONAL 时，$this->option('xxx') 在未传参时返回 null，而不是默认值；默认值只在没传 --xxx 时生效，一旦写了 --xxx 但没给值，就是 null。
- 判断是否设置了某选项：
$this->option('force') !== null（不能用isset()，因为可能为false或''） - 取带默认值的选项：
$timeout = $this->option('timeout') ?? 30，别依赖 addOption 的第四个参数兜底 - 布尔选项不要写成
$this->option('force') === true，直接用(bool) $this->option('force')或就当条件用
为什么 --env 参数在自定义命令里不生效
因为 --env 是 Artisan 启动阶段就消费的参数，用于切换应用环境配置，它不会透传到你的命令实例里。你在 handle() 中调 $this->option('env') 永远是 null。
真正生效的是 Laravel 启动时解析的 --env，它决定了 config/app.php 等文件加载哪个环境版本。你的命令运行时，环境早已固定。
- 如果真要动态切环境，得在命令启动前用
APP_ENV=staging php artisan ...，而非靠命令行选项 - 想让命令支持类似行为，自己定义
--app-env，然后在逻辑里手动重载配置（不推荐，易出错） - 多数场景下，应通过配置文件或环境变量控制行为，而不是在命令里 hack 环境
多个短选项合并写（比如 -vf）会出什么问题
Laravel 默认不支持短选项连写（-vf），只认单个字母。如果你注册了 -v 和 -f，用户输 -vf 会被当成一个叫 vf 的未知选项，报错 Unrecognized option: --vf。
这不是 bug，是 Symfony Console 的设计限制。它不自动拆分短选项组，除非你手动启用 setOptionsMode() 并配合自定义解析——但 Laravel 没暴露这个接口，也不建议折腾。
- 正确做法：只注册独立短选项，文档里明确写成
-v -f或--verbose --force - 别为了“看起来简洁”强行支持连写，维护成本高，还容易和未来 Laravel 升级冲突
- 如果真有强需求，改用
InputArgument接收位置参数，再自己 parse，但得承担所有校验逻辑
最常被忽略的是选项类型的语义差异：VALUE_REQUIRED 表示“必须跟值”，VALUE_OPTIONAL 表示“可以跟值，也可以不跟”，而 VALUE_NONE 才是纯开关。写错类型会导致用户输入合法但被拒绝，或者输入非法却静默接受。
