db_host不能写localhost，必须用云服务商提供的真实域名或ip；改.env后需运行php artisan config:clear清除配置缓存；还需检查网络白名单、公网访问开关、防火墙及mongodb连接字符串url编码等边界问题。
DB_HOST不能写localhost
远程数据库（比如云服务 Atlas、阿里云 MongoDB、腾讯云 MySQL）的地址不是 localhost，而是服务商提供的真实域名或 IP。写成 localhost 会让 Laravel 去连本机的数据库服务，必然失败。
常见错误现象：Connection refused 或超时，但本地 mysql -h 127.0.0.1 能连上 —— 这说明问题不在密码或端口，而在地址解析错了。
- MySQL/PostgreSQL 远程地址示例：
myapp-db.c9z3x1a2b4us.ap-southeast-1.rds.amazonaws.com - MongoDB Atlas 地址在连接字符串里：
cluster0.mongodb.net，不是localhost - Docker 环境下也别写
localhost，要写宿主机网关（如host.docker.internal）或实际服务容器名
环境变量必须清缓存才生效
改完 .env 文件后，Laravel 不会自动重读配置 —— 它会从 bootstrap/cache/config.php 里直接加载缓存值。不清理，新配置等于没写。
只运行 php artisan config:clear 就够了；如果已部署上线，建议用 php artisan config:cache 生成新缓存（注意：仅限生产环境，且确保 .env 完全正确后再执行）。
- 开发中误用
config:cache可能导致.env修改完全不生效，反复排查无果 -
cache:clear是清全部缓存，没必要；config:clear才是精准清除配置缓存 - CI/CD 流水线里记得加这一步，否则构建镜像时用的还是旧配置
权限和网络策略经常被忽略
连不上远程库，80% 不是 Laravel 配置问题，而是服务端拦住了请求。
必须确认三件事：
- 数据库账号是否允许从你的出口 IP 连接（Atlas 要在 Network Access 里加白名单；RDS 要配安全组；自建 MySQL 要
GRANT ... ON *.* TO 'user'@'%' IDENTIFIED BY 'pass'） - 云服务商是否开启公网访问（很多默认只限内网，比如阿里云 RDS 的“公网地址”需手动申请）
- 本地或服务器防火墙是否放行出站连接（特别是公司网络、某些云主机的 iptables/nftables 规则）
测试方法：在部署 Laravel 的机器上直接跑 telnet your-db-host 27017（MongoDB）或 nc -zv your-db-host 3306（MySQL），不通就先别调 Laravel。
MongoDB Atlas 连接字符串要严格校验
Atlas 提供的连接字符串带占位符 <username></username> 和 <password></password>，必须手动替换，且密码里如果有特殊字符（如 /、@、:），要 URL 编码。
例如密码是 pa@ss/w0rd，得写成 pa%40ss%2Fw0rd，否则解析失败，报错可能是 Invalid URI 或 Authentication failed。
- 连接字符串开头必须是
mongodb+srv://（不是mongodb://），否则无法解析 SRV 记录 -
DB_URI值两端不要加引号（.env中引号会被当字面量，导致连接串多出"） - 选项如
retryWrites=true&w=majority必须保留，删掉可能引发写入不一致
远程数据库的坑不在代码里，而在边界上——网络、权限、编码、缓存，这些环节一环断，整个链路就卡住。尤其 Atlas 用户，别只盯着 Laravel 配置，先确保 mongo --uri "your-connection-string" 能通。
