环境变量

环境变量是 Viswoole 配置系统的第一层数据源，通过 .env 文件管理不同环境的差异化配置，实现"一套代码，多环境部署"。

Env 类

框架提供 Viswoole\Core\Env 类统一管理环境变量：

php

use Viswoole\Core\Facade\Env;

// 读取环境变量
$debug = Env::get('APP_DEBUG');
$host = Env::get('DATABASE_HOST', '127.0.0.1');  // 带默认值

// 检查是否存在
if (Env::has('REDIS_PASSWORD')) {
    // 存在
}

// 获取全部变量
$all = Env::get();

// 数组式访问（需通过容器获取 Env 实例，Env 类实现了 ArrayAccess 接口）
// 注意：不能对类名直接使用数组式访问，如 Env['APP_DEBUG'] 是无效语法
$env = app('env');
$value = $env['APP_DEBUG'];

env() 辅助函数

全局辅助函数，是 Env 类的快捷方式：

php

// 基本用法
$mode = env('APP_ENV', 'production');

// 在配置文件中使用
return [
    'debug' => env('APP_DEBUG', false),
    'url' => env('APP_URL', 'http://localhost'),
];

.env 文件

文件位置

项目根目录下的 .env 文件：

text

project/
├── .env                  # 当前环境配置
├── .env.example          # 配置模板（提交到版本控制）
├── .env.testing          # 测试环境配置
├── .env.production       # 生产环境配置
└── config/
    ├── app.php
    └── database.php

文件格式

.env 文件采用 INI 格式，支持分节和注释：

ini

; ============================================
; 应用基础配置
; ============================================
APP_NAME=Viswoole应用
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:9501

; ============================================
; 数据库配置（对应 database.php，环境变量名为 DATABASE_*）
; ============================================
[DATABASE]
DATABASE_DEFAULT=default
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=viswoole
DATABASE_USER=root
DATABASE_PASSWORD=secret

; ============================================
; Redis 配置（业务自定义，框架配置文件未直接引用）
; ============================================
[REDIS]
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

; ============================================
; 缓存配置（对应 cache.php，键名为小写 cache.store）
; ============================================
cache.store=file

格式规则

规则	说明
注释	以 `;` 开头
键值对	`KEY=VALUE`
分节	`[SECTION_NAME]`
引号	框架使用 `INI_SCANNER_RAW` 模式解析，引号会被保留为值的一部分，因此值不需要加引号
空格	键名和值的首尾空格会被自动去除

分节处理

当使用分节时，键名会自动转换为 大写_连接 格式：

ini

[DATABASE]
HOST=localhost
PORT=3306

读取方式：

php

// 分节内的键通过下划线连接节名和键名
Env::get('DATABASE_HOST');      // localhost
Env::get('DATABASE_PORT');       // 3306

// 或直接用原始键名
Env::get('HOST');                // 如果不在分节内

自动类型转换

框架自动将常见字符串转换为对应的布尔值（注意：仅小写形式生效，大写形式不会被转换）：

php

// 这些字符串会被自动转换为布尔 true
env('FEATURE_ENABLED', 'true');   // → bool(true)
env('MAINTENANCE_MODE', 'on');     // → bool(true)

// 这些字符串会被自动转换为布尔 false
env('DEBUG_MODE', 'false');        // → bool(false)
env('VERBOSE_LOG', 'off');         // → bool(false)

// 注意：大写形式不会转换，保持为字符串
env('CACHE_ENABLED', 'ON');        // → string('ON')
env('DEMO_MODE', 'OFF');           // → string('OFF')

// 其他值保持原样不变
env('PORT', '9501');               // → string('9501')
env('TIMEOUT', '30');              // → string('30')

支持的转换映射:

字符串	转换结果
`'true'`, `'on'`	`true`
`'false'`, `'off'`	`false`
其他字符串	保持原样

变量名规范

内部处理规则

所有键名统一转为大写
点号 . 替换为下划线 _
分节键：SECTION_KEY 格式

php

// 写法（以下三种等价）
env('app.debug')        // 推荐写法
env('APP.DEBUG')
env('app_debug')

// 最终存储键名为 APP_DEBUG（通过 Env::get('APP_DEBUG') 读取，
// 注意 $data 是 protected 属性，不能外部直接访问）

优先级顺序

当同一变量在多个位置定义时，优先级如下：

text

.env 文件 > 系统环境变量 (getenv/$_ENV) > 默认值

框架在初始化 Env 时，先将 $_ENV 载入内部数据，再解析 .env 文件并覆盖同名键，因此 .env 文件中的定义优先于系统环境变量。仅在 .env 和 $_ENV 均未定义时，才会通过 getenv() 回退查询，最后才返回默认值。

php

// 1. .env 中定义: APP_DEBUG=true
// 2. 系统环境变量: APP_DEBUG=false (如 docker run -e APP_DEBUG=false)
// 3. 结果: env('APP_DEBUG') 返回 true (.env 文件优先)

安全注意事项

1. 不要将 .env 提交到版本控制

text

# .gitignore
.env
.env.local
.env.*.local

2. 提供 .env.example 作为模板

ini

# .env.example - 提交到版本控制
APP_NAME=YourApp
APP_ENV=local
APP_DEBUG=true

# 复制此文件并填入实际值:
# cp .env.example .env

3. 敏感信息保护

bash

# 生产环境中设置适当的文件权限
chmod 600 .env
chown www-data:www-data .env

4. 容器化部署时使用 Secrets

yaml

# docker-compose.yml
services:
  app:
    environment:
      - DATABASE_PASSWORD=#123;DATABASE_PASSWORD} # 从外部传入或使用 Docker secrets

常见配置项参考

以下环境变量名需与 config/ 下对应配置文件中 env() 调用的键名保持一致，否则不会被框架读取。

应用配置

对应 config/app.php：

ini

; app.php 使用小写键名
default_timezone=Asia/Shanghai
app_debug=true                       # 生产环境必须设为 false

说明：app.php 中并未引用 APP_NAME、APP_ENV、APP_URL 等键，这些可作为业务自定义变量使用。

数据库配置

对应 config/database.php：

ini

DATABASE_DEFAULT=default
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=viswoole
DATABASE_USER=root
DATABASE_PASSWORD=your_password_here

Redis 配置

框架内置配置文件未直接引用 Redis 环境变量，以下为业务自定义约定（如在 cache.php 中自定义 redis store 时使用）：

ini

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=
REDIS_PORT=6379
REDIS_DB=0

日志配置

config/log.php 中的 default、trace_source、console 均为硬编码值，不通过环境变量配置。如需按环境差异化配置，可自行修改 log.php 引入 env() 调用。

缓存配置

对应 config/cache.php（使用小写键名）：

ini

cache.store=file                    # file | redis（redis 需在 cache.php 中自行配置 store）