关键在合并逻辑：+运算符补缺、array_merge()覆盖重排数字键、array_replace()保序、ArrayHelper::merge()递归合并嵌套结构，需按场景选型，否则配置静默失效。
直接用数组合并实现配置覆盖，关键不在“怎么合”，而在“按什么逻辑合”——不同场景要选不同合并方式，否则默认行为会悄悄改掉你的配置。
配置覆盖的核心原则：谁优先、是否递归、键怎么处理
配置项本质是关联数组，合并时必须明确三件事：
- 覆盖方向：是“默认值兜底、用户配置优先”，还是“基础配置为主、局部补丁覆盖”
-
嵌套结构：比如
['db' => ['host' => '127.0.0.1', 'port' => 3306]]，只替换 host 还是整个 db 子数组？ - 键类型敏感度：数字键（如日志 handlers 列表）要保留顺序，字符串键（如组件名）要支持字段级覆盖
四种典型配置合并方式及适用场景
别硬记函数名，看它解决什么问题：
-
+ 运算符：适合“默认配置 + 用户配置”。左侧键存在就不动，右侧只补缺。例如：
$config = $defaults + $userConfig，$userConfig['debug']未设时，$config['debug']仍用默认值。 -
array_merge()：适合“逐层叠加、后写为准”。字符串键被右值覆盖，数字键重排。常用于扁平化参数拼接，比如 API 请求参数：
array_merge($baseParams, $extra)。 -
array_replace()：和
array_merge()类似但不重排数字键。适合需要保持索引顺序的列表类配置，如中间件队列：['AuthMiddleware', 'LogMiddleware']和['CorsMiddleware']合并后仍保持原顺序。 -
ArrayHelper::merge()（Yii）或 array_replace_recursive()：唯一能安全处理嵌套结构的方案。同名子数组会递归合并，不是整块替换。比如
['log' => ['targets' => [...]]]可单独加一个 target 而不影响其他 log 配置。
实战：合并多组变量参数的常见模式
真实代码里参数往往来自多个来源，合并前先统一转数组再操作，避免 array_merge() 报 warning：
- 环境变量 + 默认值：
$config = array_replace($defaults, $_ENV ?? []); - 请求参数动态组装：
$params = [...$base, ...$dynamic];（PHP 7.4+ 展开语法，简洁且高效） - 多级配置文件叠加：
$config = yii\helpers\ArrayHelper::merge(require 'main.php', require 'local.php'); - 安全兜底写法：
$merged = array_merge([], $a ?? [], $b ?? [], $c ?? []);—— 空或 null 全转空数组，不中断执行
容易踩坑的细节提醒
这些点不注意，配置就静默失效：
-
file_exists() 检查必须显式写：像
main-local.php不是自动加载，得靠if (file_exists(...)) { merge(...) }手动触发 -
不要用 include_once 替代 require：配置文件缺失时，
include_once返回 false 导致空数组，require直接报错中止，更容易暴露问题 -
array_merge_recursive() 会把标量变数组：比如
'debug' => true和'debug' => false合并后变成'debug' => [true, false]，框架直接崩溃 -
Docker 中权限问题：COPY 进容器的
main-local.php若不可读，file_exists()返回 false，配置丢弃无提示
