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

ThinkPHP数据库配置中.env变量名必须全大写、下划线分隔、无空格或特殊前缀，否则env('DB_HOST')返回false/null导致连接失败；不支持INI分段、大小写敏感、不自动转换，推荐DB_HOST、DB_NAME等标准命名。

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

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

所有数据库相关变量需严格使用大写字母和下划线组合，不能驼峰、不能小写、不能带点或中划线：

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

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

ThinkPHP 不支持 INI 风格的分段写法，.env 必须是扁平键值对：

• ✅ 正确：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 这个键名，不会做大小写归一化或别名映射。

立即学习“PHP免费学习笔记（深入）”；

• 团队协作时，建议在项目根目录放一份 .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 ❌