Yii2环境配置需在入口脚本顶部用vlucas/phpdotenv预加载.env，配置中getenv()必须设默认值，敏感字段DSN需urlencode处理，多环境通过APP_ENV变量路由配置文件。
Yii2 没有“全局变量”机制，但有一套成熟、安全、可版本控制的环境变量配置体系。核心不是写死值，而是分层加载 + 显式兜底 + 作用域隔离。只要按规范走，开发、测试、生产三套环境就能稳定切换，敏感信息也不会泄露。
入口处必须预加载 .env
Yii 本身不读 .env，所有 getenv() 调用都依赖 PHP 进程启动时的环境状态。必须在 web/index.php 或 yii 命令行入口最顶部（autoload 之后、Yii.php 加载之前）完成加载：
- 先安装：
composer require vlucas/phpdotenv - 再插入代码（路径指向项目根目录）：
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');<br>$dotenv->load();
- 推荐加
$dotenv->safeLoad();自动加载 .env.local（本地调试专用，不提交 Git）
配置文件里用 getenv() 必须设默认值
环境变量缺失是线上故障高频原因。config/main.php、config/db.php 等任何地方写 getenv('DB_HOST')，都得立即补上 fallback：
'host' => getenv('DB_HOST') ?: 'localhost'-
'port' => (int)getenv('DB_PORT') ?: 3306（强转防字符串误用） -
'username' => urlencode(getenv('DB_USER') ?: 'root')（特殊字符如 @ / # 必须编码）
敏感字段要单独处理 DSN 结构
数据库密码、用户名、库名若含 @、/、:、#，直接拼进 DSN 会解析失败。正确做法是只对变量值做 urlencode：
- 错误：
'dsn' => 'mysql:host=localhost;dbname='.getenv('DB_NAME').' - 正确：
'dsn' => 'mysql:host='.getenv('DB_HOST').';dbname='.urlencode(getenv('DB_NAME') ?: 'app') - 密码同理：
'password' => urlencode(getenv('DB_PASSWORD') ?: '')
多环境切换靠 APP_ENV + 配置文件路由
不推荐硬编码 YII_ENV 常量来区分环境，更灵活可靠的方式是：
- 定义系统级环境变量：
export APP_ENV=prod（Linux/macOS）或系统属性设置（Windows） - 修改 web/index.php 中配置加载逻辑：
$configFile = __DIR__.'/../config/'.getenv('APP_ENV').'.php';<br>if (file_exists($configFile)) {<br> $config = require $configFile;<br>} else {<br> $config = require __DIR__.'/../config/web.php';<br>} - 在 config/ 目录下建
dev.php、test.php、prod.php，各自覆盖日志级别、缓存开关、调试工具等关键项
