DBAL3抛出Named parameter "receivedOn"未绑定值错误 原DBAL2可正常运行

这个报错本质是DBAL3对命名参数的绑定校验、SQL解析逻辑比DBAL2严格很多，之前DBAL2能容错的不规范写法，升级后会直接抛错，按以下方向逐一排查即可：

• 先核对参数名的严格匹配：DBAL2对命名参数是大小写不敏感的宽松匹配，比如SQL里写:receivedon，绑定参数时传receivedOn也能正常识别；DBAL3是完全大小写敏感的逐字符匹配，占位符和绑定键名差一个字符、下划线/驼峰写错都认不出来。另外要注意不要把命名参数写在SQL的字符串字面量、注释里，DBAL3的解析器会把这些位置的占位符也识别为待绑定参数，漏绑就会报错。
• 检查参数绑定方式与类型声明：DBAL2支持在execute()方法里直接传参数数组，还会自动做DateTime等特殊类型的隐式转换，DBAL3废弃了这套隐式逻辑。如果还保留DBAL2时期的旧写法，直接给execute()传带receivedOn键的数组，大概率会出现参数识别失败的问题。建议改成显式调用setParameter()绑定，同时声明对应参数类型，参考写法：

// DBAL3 正确绑定示例
use Doctrine\DBAL\Types\Types;

$qb = $conn->createQueryBuilder()
    ->select('*')
    ->from('trade_order')
    ->where('received_at = :receivedOn')
    // 显式绑定参数+声明类型，不要靠隐式推断
    ->setParameter('receivedOn', $receivedTime, Types::DATETIME_MUTABLE)
    ->executeQuery();

• 排查自定义类型与重复占位符问题：如果receivedOn字段用了自定义的DBAL Type，重点检查convertToDatabaseValue方法的返回值逻辑，返回值异常会被判定为绑定无效。另外DBAL3 3.0~3.2版本存在已知解析bug：SQL里多次复用同一个命名参数时，会被识别成多个独立参数，只绑定一次就会报缺值，升级到3.3及以上版本即可修复这个问题。
• 做最小场景验证：可以临时把:receivedOn改成问号占位符，按顺序传值试跑，如果能正常执行，就能确定问题出在命名参数的解析、匹配环节，和参数值本身、SQL业务逻辑无关。如果还是报错，直接打印SQL预处理阶段解析出的所有待绑定参数列表，和你实际传入的绑定数组逐键比对，很快就能找到漏配、错配的点。

内容的提问来源于stack exchange，提问作者Beenzie