本质是环境变量加载时机错位：定时任务在Worker进程启动时初始化，但.env文件尚未被完整解析，导致依赖环境变量的组件（如数据库、Redis）提前注册失败，@Cron类无法完成DI容器注入而静默退出。
Hyperf 环境变量读取异常导致定时任务进程启动失败，本质不是“变量没读到”，而是变量加载时机错位——定时任务在 Worker 进程启动时就初始化，但此时 .env 或配置文件尚未被完整解析，尤其当依赖环境变量的组件（如数据库、Redis）提前注册或校验失败时，整个 @Cron 注解类甚至无法完成 DI 容器注入，直接静默退出或报错中断。
确认是否真为环境变量问题
别急着改 .env，先排除干扰：
- 检查
config/autoload/app.php中'env' => env('APP_ENV', 'production')是否能正常输出（可在命令行执行php bin/hyperf.php di:dump查看实际解析值） - 运行
php bin/hyperf.php cron:list—— 若命令报错（如Class not found或Connection refused），说明容器构建阶段已失败，不是运行时读取问题 - 查看
runtime/logs/crontab.log，重点找Dotenv\InvalidPathException、Undefined index或ConnectionException类错误，它们往往暴露真实断点
定时任务启动前环境变量未就绪的典型场景
常见于三类配置耦合：
-
数据库连接池初始化早于 .env 加载：若
config/autoload/database.php中直接用了env('DB_HOST')，而该文件又被DbConnection服务提供者在容器启动早期 require，此时Dotenv可能还未触发加载 -
自定义 CronCommand 类依赖未注入服务：比如你在
@Cron方法里直接 new 了一个需要 Redis 的类，但 Redis 客户端因REDIS_HOST为空而构造失败，抛出异常后 cron dispatcher 直接跳过该任务 -
K8s ConfigMap 挂载延迟：容器启动时
/etc/config/.env文件存在但内容为空或不全，Swoole Worker 已开始初始化，后续即使文件写入完成也无法重新触发 dotenv 加载
可靠加载方案：强制延迟 + 显式兜底
不依赖框架自动加载顺序，主动控制变量可用性：
- 在
config/autoload/database.php等关键配置中，用env('DB_HOST', '127.0.0.1')提供强默认值，避免空字符串引发 PDO 构造失败 - 将定时任务入口类（如
App\Command\MyCronCommand）改为实现Hyperf\Contract\OnStartInterface，在onStart()回调里做环境校验：if (! env('API_KEY')) { throw new RuntimeException('Missing required env: API_KEY'); } - 对高风险变量加运行时断言：在
@Cron方法开头插入assert(env('QUEUE_DRIVER'), 'QUEUE_DRIVER must be set');—— PHP 8+ 支持，失败直接中止且带清晰提示
调试技巧：让 cron 启动过程“开口说话”
Hyperf 默认静默失败，需主动暴露上下文：
- 在
app/Process/CronDispatcherProcess.php（如有自定义）或config/autoload/processes.php中，给 cron 进程增加日志前缀：'redirect_stdout' => true, 'redirect_stderr' => true, 'pipe' => 2,并确保runtime/logs/crontab.log权限可写 - 临时在
app/Command/YourCronCommand.php的handle()开头加：var_dump(['env_APP_ENV' => env('APP_ENV'), 'getenv' => getenv('APP_ENV')]);—— 对比env()和getenv()输出，确认是否被putenv()覆盖 - 用
ps aux | grep hyperf查看实际启动的 worker 进程命令行，确认是否带--env=production参数（部分部署脚本会覆盖.env）
环境变量不是开关，是启动链上的齿轮。错一齿，整条链停转。重点不在“怎么读”，而在“谁先读、谁等谁”。
