ThinkPHP升级后的配置文件格式变化_新版本配置注入技巧-ThinkPHP-PHP中文网

thinkphp 6+ 强制采用模块化 config/ 目录结构，配置须为纯数组并置于对应 php 文件中；环境变量仅覆盖一级键且严格区分大小写与下划线；自定义配置需显式加载；推荐使用 think\facade\config 读取，容器注入应避免废弃类并统一命名规范。

thinkphp升级后的配置文件格式变化_新版本配置注入技巧

ThinkPHP 6+ 的 config 目录结构彻底变了

旧版的 config.php 单文件配置被拆成按模块组织的 PHP 文件，比如 app.php、database.php、cache.php。这不是“可选优化”，而是强制结构——框架启动时会自动合并这些文件，不再读取根目录下的 config.php。

常见错误现象：Undefined index: database 或 Class 'think\Config' not found，本质是代码还在用 Config::get('database.host') 但新版本已移除静态类访问方式。

所有配置必须放在 config/ 目录下对应文件中，返回纯数组（不能带 return 以外的逻辑）
环境配置（如 .env）优先级高于 PHP 配置，但只支持键值对，不支持嵌套数组
think\facade\Config 是唯一推荐的读取入口，写法是 Config::get('database.hostname')（注意是 hostname，不是 host）

如何安全迁移旧版 config.php 中的自定义配置

很多人把业务参数（比如支付密钥、第三方 API 地址）全塞进旧版 config.php，升级后直接丢进 config/custom.php 就报错——因为新版本默认不加载非标准配置文件。

必须显式注册：在 app/bootstrap.php 或服务提供者里调用 Config::load()，否则 Config::get('custom.pay_key') 永远返回 null。

新建 config/custom.php，返回数组，例如：

return ['pay_key' => env('PAY_KEY', ''), 'api_timeout' => 5000];

在 app/bootstrap.php 开头添加：think\facade\Config::load(__DIR__ . '/../config/custom.php', 'custom');
环境变量名必须全大写、下划线分隔，PAY_KEY 才能被 env('PAY_KEY') 正确读取

多环境配置覆盖失效的典型原因

写了 .env，也改了 config/database.php，但 Config::get('database.hostname') 还是返回 PHP 文件里的值——说明环境变量没生效，或配置键名不匹配。

ThinkPHP 6+ 的环境变量仅覆盖「一级键」，且严格区分大小写和下划线/点号。比如 DATABASE_HOSTNAME=127.0.0.1 可以覆盖 database.hostname，但 DATABASE_HOST 不行，database.host 也不行（因为配置里实际是 hostname）。

.env 文件必须放在项目根目录，且不能有 BOM 头
确认 config/database.php 中存在 'hostname' => env('DATABASE_HOSTNAME', '127.0.0.1') 这种兜底写法
运行 php think clear:config 清理配置缓存，否则修改 .env 后不会实时生效

配置注入到容器时的命名陷阱

想把配置值自动注入到控制器或服务类构造函数？别直接依赖 think\Config，它不是容器绑定的服务；要用 think\facade\Config 静态门面，或者手动绑定配置实例。

更稳妥的做法是：在服务提供者中把关键配置项作为参数注入容器，避免每次调用都走门面解析路径。

不要这样写：public function __construct(\think\Config $config) —— think\Config 类已被废弃
可以这样绑定：$this->app->bind('pay.client_id', function () { return Config::get('custom.pay_client_id'); });
然后在构造函数中类型提示 string $payClientId，并配置容器参数映射

配置键名带点号（如 custom.pay_key）在容器参数映射里会被截断，建议统一用下划线命名，比如 custom_pay_key，减少歧义。