Hyperf 环境变量通过 .env 文件管理并自动加载，支持多环境配置（如 .env.production），需通过 HYPERF_ENV 指定；所有 .env 值均为字符串，必须显式类型转换（如 (int)env()、filter_var(..., FILTER_VALIDATE_BOOLEAN)）；敏感信息应由系统环境变量注入，.env 文件须忽略 Git；配置优先级为：系统环境变量 > .env 中 env() 调用 > 配置文件默认值。
Hyperf 安装完成后，环境变量主要通过 .env 文件管理，配合 env() 函数读取，但需注意类型安全与加载优先级——不是写进去就能直接用，关键在“怎么设”和“怎么读”。
环境变量文件位置与命名规范
默认使用项目根目录下的 .env 文件。Hyperf 会自动加载它，无需手动引入。若需多环境隔离，可创建：
-
.env.local（本地开发） -
.env.production（生产环境） -
.env.testing（测试环境）
通过设置系统级环境变量 HYPERF_ENV 指定当前生效的配置文件，例如：
Linux/macOS：export HYPERF_ENV=production
Windows（PowerShell）：$env:HYPERF_ENV="production"
配置项写法与类型转换要点
所有值在 .env 中都是字符串，即使写成数字或布尔值。Hyperf 3.0+ 对类型校验严格，直接用于数值型配置会报错。必须显式转换：
- 端口配置（如
server.php）：'port' => (int)env('SERVER_HTTP_PORT', 9501) - 数据库端口：
'port' => (int)env('DB_PORT', 3306) - 开关类配置：
'debug' => filter_var(env('APP_DEBUG', 'true'), FILTER_VALIDATE_BOOLEAN)
避免写成 'port' => env('SERVER_HTTP_PORT', 9501) —— 这会导致类型错误，服务无法启动。
敏感信息与安全配置建议
数据库密码、API密钥、JWT密钥等绝不允许写死在配置文件中，必须通过环境变量注入：
-
.env中只写占位标识：DB_PASSWORD=${DB_PASSWORD}（不推荐）或更稳妥地留空：DB_PASSWORD=，由系统环境变量提供 - 部署时通过系统级方式注入：Docker 使用
--env DB_PASSWORD=xxx；Linux 服务用Environment=DB_PASSWORD=xxx（systemd） - 确保
.env文件不在 Git 提交中，添加到.gitignore
配置加载顺序与覆盖逻辑
Hyperf 配置按优先级从高到低生效：
- 操作系统环境变量（最高，如
DB_HOST=192.168.1.100） -
.env文件中的env()调用（次之） - 配置文件中硬编码的默认值（兜底，如
'host' => '127.0.0.1'）
这意味着：系统环境变量能直接覆盖 .env 内容，适合容器化或 CI/CD 场景动态切换配置。
