database_url必须严格遵循dsn格式:driver://user:pass@host:port/db?options;漏//、空格、中文符号或特殊字符未url编码(如@→%40)均会导致连接失败或静默回退。

DATABASE_URL 格式必须严格匹配 Symfony 的 DSN 规范
Symfony 不解析任意字符串,只认标准 DSN(Data Source Name)格式:driver://user:password@host:port/database?options。漏掉 //、多一个空格、用中文冒号,都会导致 ConnectionException 或静默 fallback 到 SQLite。
常见驱动写法与易错点
PostgreSQL、MySQL、SQLite 三者参数差异大,尤其密码和数据库名里的特殊字符必须 URL 编码:
- PostgreSQL:
postgresql://db_user:my%40pass@127.0.0.1:5432/myapp?serverVersion=15(注意@要写成%40) - MySQL:
mysql://root:secret@localhost:3306/symfony_app?charset=utf8mb4(charset建议显式指定) - SQLite:
sqlite:///%kernel.project_dir%/var/data.db(路径必须是绝对路径,%kernel.project_dir%会被自动展开)
本地开发常用简写与陷阱
环境变量里写 DATABASE_URL=sqlite:///%kernel.project_dir%/var/app.db 看似方便,但实际运行时可能报 Database does not exist —— 因为 Symfony 默认不自动创建 SQLite 目录。
- 确保
var/目录可写,且var/data.db所在父目录已存在 - MySQL/PostgreSQL 连接失败时,先用
telnet host port或nc -zv host port验证端口连通性,别急着改 DSN - 使用 Docker 时,
host不能写localhost,得用服务名(如db),否则容器内访问不到宿主的 127.0.0.1
敏感信息别硬编码,优先走环境变量
.env 文件里写 DATABASE_URL=mysql://$DB_USER:$DB_PASS@$DB_HOST:$DB_PORT/$DB_NAME,再在 .env.local 中定义各变量,比直接拼完整 URL 更安全、更易切换环境。
-
$DB_PASS含/、?、@时,必须用urlencode处理后再赋值给变量 - 部署到生产时,确保系统级环境变量覆盖了
.env,Symfony 会按$_ENV → $_SERVER → .env顺序读取











