ThinkPHP数据库配置env变量命名规范团队

ThinkPHP 数据库配置中，.env 文件的变量命名必须遵循特定规则：全大写、下划线分隔，不能有空格或特殊前缀。否则，env('DB_HOST') 会返回 false 或 null，导致数据库连接失败。这不是风格建议，而是框架底层解析器（vlucas/phpdotenv）的硬性要求。

该限制来自框架底层使用的 vlucas/phpdotenv 解析器，是其设计特性而非风格建议。许多开发者初学时容易在此细节上出错，因此有必要详细说明。

变量名必须全大写 + 下划线

所有数据库相关变量必须严格使用大写字母和下划线组合，不能使用驼峰、小写、点号或中划线。直接看示例：

• 正确：DB_HOST、DB_NAME、DB_PREFIX、DB_PORT
• 错误：db_host、DbHost、database_host、DB-Host、DB.HOST

对比可见，env() 函数只识别全大写加下划线的键名，任何一个字符错误都会导致读取失败。

不能加段落标签或嵌套结构

ThinkPHP 不支持 INI 风格的分段写法，.env 必须为扁平键值对。使用 [database] 这类分组头会被完全忽略，变量无法读取。

• 正确：DB_HOST=127.0.0.1
• 错误：[database]
DB_HOST=127.0.0.1（完全无效）

简单来说，每一行一个键值对，无需额外结构。

大小写敏感，且不自动转换

即使在 config/database.php 中写 'hostname' => env('db_host', '127.0.0.1')，也不会生效——env() 函数只识别 DB_HOST 这个键名，不会进行大小写归一化或别名映射。小写写法无法被识别。

团队协作时，建议在项目根目录放置一份 .env.example，统一声明标准变量名。CI/CD 流程中可加入校验脚本，检查 .env 是否存在非法命名（如含小写字母、点号、中划线），这能有效减少排查时间。

常见易错变量名对照表

以下为高频误写与推荐写法对比，团队文档可直接引用：

• DB_USER ｜db_user ｜DB_USERNAME （ThinkPHP 默认不识别，除非在 database.php 中主动定义）
• DB_PWD ｜PASSWORD ｜DB_PASSWORD （官方示例和核心约定均为 DB_PWD）
• DB_PREFIX ｜TABLE_PREFIX ｜prefix
• DB_CHARSET ｜CHARSET ｜DB_ENCODING

核心原则：严格遵循官方约定的命名，不要自行简写。许多线上故障最终原因只是 .env 中写了一个小写变量。