ThinkPHP数据库密码含特殊字符时连接失败，主因是环境变量未正确读取：密码须用双引号包裹、等号两侧禁空格、database.php中必须调用getenv('DB_PASSWORD')。
ThinkPHP 数据库密码含特殊字符（如 @、#、!、%、$）时，连接失败往往不是密码本身错了，而是环境变量没被正确读取——解析被截断或静默失效，导致认证拒绝、调试模式意外开启、甚至凭据泄露。
密码必须用双引号包裹
未加引号的 DB_PASSWORD 值在新版 vlucas/phpdotenv（TP6/TP8 默认依赖）中会被当作 shell 变量或注释处理：
-
❌ 错误写法：DB_PASSWORD=abc@123#test →
#后内容被当注释丢弃，@可能触发变量展开，实际读到的只剩abc - ✅ 正确写法：DB_PASSWORD="abc@123#test"
- 单引号虽可避免 shell 解析，但新版 dotenv 对单引号内
$不展开（TP 不依赖此特性），为兼容 Laravel 生态和 CI 工具链，统一用双引号更稳妥 - 验证方式：在控制器中执行
dump(getenv('DB_PASSWORD'))，输出必须与 .env 中完全一致
等号两侧绝对不能有空格
.env 文件格式极其严格，任意空格都会导致整行被跳过，且无任何报错提示：
- ❌ 错误写法：DB_HOST = 127.0.0.1（等号前后有空格）→ 整行失效，env('DB_HOST') 返回 null
- ✅ 正确写法：DB_HOST=127.0.0.1
- 编辑器开启“显示不可见字符”，确认无全角空格、零宽字符或制表符
- 避免从微信、WPS 或 Word 复制内容——它们常插入非法空白符
- 怀疑格式问题时，Linux/macOS 下可用
cat -A .env查看是否含^M或M-bM-^@类字节
DSN 字符串中的特殊字符要 urlencode
若在配置中直接使用 DSN（如 mysql://user:pass@host/db），用户名或密码含 @、:、/、# 会触发 parse_url() 截断：
立即学习“PHP免费学习笔记（深入）”；
- 例如密码为
abc@123，DSN 解析后变成mysql://user:abc@，后续乱码导致 PDO 连接拒绝 - 必须对用户名和密码单独做
urlencode()：$pwd = urlencode('abc@123'); $dsn = "mysql://user:{$pwd}@host/db"; - 主机、端口、库名、字符集无需编码
- 注意：TP6 已不再支持裸 DSN 字符串传给
Db::connect()，必须改用数组配置或封装为合法数组结构
database.php 中必须显式引用环境变量
即使 .env 配置正确，如果 config/database.php 里仍写死密码或未调用 getenv()，环境变量就完全不起作用：
-
❌ 错误写法：
'password' => 'hardcoded123'→ .env 中的 DB_PASSWORD 永远不会生效 -
✅ 正确写法：
'password' => getenv('DB_PASSWORD') ?: '' - 确保 .env 文件位于项目根目录，文件名就是纯
.env（无后缀、无空格） - 部署时通过 CI/CD 自动注入敏感字段，或把
database.php拆成公共配置 + 环境变量加载两部分，避免凭据进 Git - 在 CI 流水线中加入检查：
grep -q "password\|passwd" config/database.php && exit 1
不复杂但容易忽略。关键就三点：引号包住密码、等号不留空格、代码里真去读它。
