ThinkPHP数据库连不上90%因.env未加载或格式错误：必须放根目录、APP_DEBUG=true、键名全大写下划线、等号无空格、值含特殊字符需单引号包裹，且需清缓存重启进程。
ThinkPHP数据库配置总连不上，90%的情况不是密码错了、服务没开，而是.env文件根本没被框架读到，或者读到了但格式一丁点不对就静默失效——它不报错，只悄悄返回null，然后用默认的127.0.0.1和空密码去连，自然失败。
确认.env是否真被加载了
别猜，直接验证。在public/index.php最开头插入三行调试代码（上线前务必删掉）：
```php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/..');
$dotenv->safeLoad();
var_dump($_ENV['DB_HOST'] ?? 'not in $_ENV', getenv('DB_HOST') ?: 'not in getenv');exit;
```
如果两个都输出not in，说明文件压根没加载；如果只一个有值，说明框架env()函数桥接失败。这一步必须做，否则后面全在蒙。
立即学习“PHP免费学习笔记（深入）”；
.env文件位置和命名硬性要求
ThinkPHP 6+ 只认项目根目录下、名字就是.env的文件，不多一个字符，不少一个点。
方法一：检查是否放错位置
必须和composer.json、think、app、config这些目录/文件同级，不能放在config/.env或public/.env里——放错等于没写。
方法二：检查文件名是否带隐藏后缀
Windows记事本保存时容易生成.env.txt，Mac Finder可能显示为.env但实际是.env?。终端执行ls -la | grep "\.env"，确认输出只有.env，没有其他变体。
【文件必须是UTF-8无BOM编码】——带BOM会导致vlucas/phpdotenv解析整行跳过，所有变量为空，且完全不报错。
键名和值的格式雷区
ThinkPHP只识别DB_*系列大写+下划线命名，且等号两侧绝对不能有空格。
第一步：键名必须全大写+下划线
✅ DB_HOST=127.0.0.1
❌ db_host=127.0.0.1（小写）
❌ DbHost=127.0.0.1（驼峰）
❌ DATABASE_HOST=127.0.0.1（非DB_前缀，框架不识别）
第二步：等号前后禁止空格
✅ DB_PORT=3306
❌ DB_PORT = 3306（右侧空格→该行被跳过）
❌ DB_PORT= 3306（左侧空格→同样被跳过）
第三步：密码含特殊字符必须单引号包裹
✅ DB_PASS='p@ss#word!'
❌ DB_PASS=p@ss#word!（#被当注释，!被shell解析）
❌ DB_PASS="p@ss#word!"（双引号在CLI下可能被shell提前处理）
APP_DEBUG必须为true才加载.env
这是最常被忽略的一点：ThinkPHP 6+ 默认只在APP_DEBUG=true时才执行.env加载逻辑。如果APP_DEBUG=false，框架直接跳过整个.env读取流程，哪怕文件存在、路径正确、格式完美，也完全无效。
验证方式：在控制器里加一行dump(env('APP_DEBUG'));，输出null或false就说明加载被跳过。
【APP_DEBUG必须是字符串"true"或布尔true，"1"、"on"、"yes"全部无效】
host和port配置的底层陷阱
localhost ≠ 127.0.0.1，在macOS/Linux下会走Unix socket，而ThinkPHP PDO连接强制走TCP，结果就是“SQLSTATE[HY000] [2002] No such file or directory”。
方法1：host统一写127.0.0.1
✅ DB_HOST=127.0.0.1
❌ DB_HOST=localhost（尤其Mac M1 + Homebrew MySQL时必挂）
方法2：port必须是整数类型
✅ DB_PORT=3306（无引号）
❌ DB_PORT='3306'（字符串→PDO静默fallback到默认端口）
注意：TP6的database.php里字段名是'hostport'，不是'port'；TP5才是'DB_PORT'。
Docker环境要换host：不能写127.0.0.1或localhost，得用容器名（如mysql）或host.docker.internal。
清缓存并重启服务
ThinkPHP会把.env解析结果缓存进runtime/config/，改了.env却不生效，大概率是缓存没清。
第一步：删除缓存目录
执行php think clear:config 或手动删除runtime/config/下的所有文件。
第二步：重启Web服务或CLI进程
Nginx/Apache需重载，Swoole/Workerman必须kill进程再启动——.env只在进程启动时加载一次，改完不重启等于白改。
