main-local.php 不生效主因是加载顺序或路径错误；它依赖 main.php 末尾的 file_exists + ArrayHelper::merge 手动合并逻辑，且必须与 main.php 同目录、权限可读。
为什么 main-local.php 不生效？
绝大多数情况是加载顺序或路径不对。Yii 的配置合并逻辑是「先载入 main.php，再尝试载入同目录下的 main-local.php」，但这个行为只在 require_once 显式写死的地方触发——比如默认的 web/index.php 里那行：require(__DIR__ . '/../config/main.php');，它本身**不自动追加 -local 版本**。
真正起作用的是 main.php 文件末尾那一段：
if (file_exists(__DIR__ . '/main-local.php')) {
$config = yii\helpers\ArrayHelper::merge($config, require __DIR__ . '/main-local.php');
}
所以如果你删了这段、挪动了 main-local.php 到别的目录、或者用 Composer 自动加载方式绕过了 main.php 的手动合并逻辑，main-local.php 就彻底被无视。
- 检查
main.php是否保留了上述file_exists+ArrayHelper::merge块 -
main-local.php必须和main.php在同一级目录（如config/） - 文件权限要确保 Web 进程能读取，尤其在 Docker 或部署后容易因复制方式丢失可读性
main-local.php 适合放什么？不适合放什么？
它本质是「覆盖层」，不是「环境切换开关」。Yii 没有内置多环境（dev/staging/prod）自动识别机制，main-local.php 只是本地开发时方便覆盖敏感配置的约定俗成文件名。
立即学习“PHP免费学习笔记（深入）”；
适合放：
'db' => ['dsn' => 'mysql:host=localhost;dbname=myapp_dev']'mailer' => ['useFileTransport' => true]-
'bootstrap' => ['debug', 'gii']（仅本地启用调试工具）
不适合放：
- 数据库密码硬编码（应改用
getenv()或$_ENV） - 条件判断逻辑（如
if (YII_ENV === 'prod') {...}）——它不该承担环境路由职责 - 任何需要版本控制的内容（
.gitignore必须包含main-local.php）
和 environments/ 目录方案冲突吗？
冲突，而且是设计意图上的根本冲突。environments/ 是 Yii 官方提供的「多环境生成」方案，靠 init 命令把模板（如 environments/dev/config/web.php）复制到 config/ 下并替换占位符；而 main-local.php 是运行时动态合并，不依赖命令行初始化。
两者混用极易出问题：
- 如果已用
init生成过config/web.php，它里面通常**没有**那段file_exists(...-local.php)合并逻辑 -
environments/生成的配置默认把main-local.php当作额外补丁，但实际是否加载取决于你最终使用的入口文件（web/index.php加载哪个 config） - 本地开发用
main-local.php，上线又切回environments/，很容易漏掉某处的配置差异，导致行为不一致
建议二选一：小项目直接用 main-local.php + getenv()；中大型项目统一走 environments/，别在生成后的 config 里再塞 -local 逻辑。
getenv() 和 main-local.php 能一起用吗？
能，而且应该一起用。把密钥类配置从 main-local.php 移到环境变量，既避免误提交，又让本地和容器部署逻辑一致。
例如，在 main-local.php 中写：
return [
'components' => [
'db' => [
'dsn' => getenv('DB_DSN') ?: 'mysql:host=localhost;dbname=test',
'username' => getenv('DB_USER') ?: 'root',
'password' => getenv('DB_PASS') ?: '',
],
],
];
然后在本地 .env 或 Docker environment: 块里设好值。注意两点：
-
getenv()默认不读取.env文件，需配合vlucas/phpdotenv手动加载（Yii2 官方模板已内置） - 某些 SAPI（如 PHP-FPM）默认禁用
getenv()，需在php.ini开启variables_order = "EGPCS"并确保E在其中
最常被忽略的是：Docker 容器内 PHP 进程可能没继承宿主机的 ENV，必须显式用 environment: 或 env_file: 注入，不能只靠 .env 文件存在就以为变量可用。
