PDO 原生预处理怎么配置或排查

PDO 的“原生预处理”不是把 prepare() 写出来就一定启用。以 PHP 的 PDO_MYSQL 为例，先确认驱动已加载，再在创建连接时显式设置 PDO::ATTR_EMULATE_PREPARES 为 false，并用 getAttribute() 回读属性。还要记住：占位符只能代表值，不能代表表名、列名或排序方向。

官方地址：https://www.php.net/manual/en/

PDO 原生预处理先看这三个配置点

第一个点是驱动。PDO 只是统一接口，真正执行 MySQL 语句的是 pdo_mysql；没有它，连接字符串写得再正确也无法完成 PDO_MYSQL 连接。第二个点是模拟开关：PHP 手册说明，true 会始终模拟预处理，false 会尝试原生预处理，但驱动无法成功准备某条语句时仍可能回退到模拟方式。第三个点是错误模式，它决定失败是返回 false，还是直接抛出 PDOException。

最小配置可以集中放在构造函数的第四个参数中：

 PDO::ERRMODE_EXCEPTION,
    // false 表示优先请求驱动提供的原生预处理。
    PDO::ATTR_EMULATE_PREPARES => false,
];

try {
    // 生产环境从环境变量或密钥管理服务读取账号，不把真实密码写入代码。
    $pdo = new PDO($dsn, $username, $password, $options);
} catch (PDOException $e) {
    // 连接失败时记录受控信息，避免把数据库密码或完整 DSN 回显给用户。
    throw new RuntimeException('数据库连接失败', 0, $e);
}
?>

这里的 charset=utf8mb4 是 DSN 的连接参数，不是预处理开关；它解决字符集协商问题。ATTR_EMULATE_PREPARES 也不是“防注入万能开关”，安全前提仍是 SQL 结构固定、用户输入只通过参数绑定。

用一个最小查询确认参数绑定

配置后不要只看代码，而要用一条带值参数的查询确认调用方式。命名占位符适合表达字段含义，绑定整数时显式使用 PDO::PARAM_INT，这样排查时不会把字符串转换误认为预处理失效。

prepare(
    'SELECT id, email FROM users WHERE status = :status ORDER BY id DESC LIMIT :page_size'
);

// 用明确的 PDO 类型绑定值，便于定位 LIMIT 或比较条件的类型问题。
$stmt->bindValue(':status', 'active', PDO::PARAM_STR);
$stmt->bindValue(':page_size', 20, PDO::PARAM_INT);
$stmt->execute();

// FETCH_ASSOC 只取列名键，减少后续读取时的歧义。
$rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
?>

如果你的 MySQL/驱动组合对某个位置的原生绑定有限制，先把查询缩减为 WHERE status = :status 这样的最小案例，再逐项加回排序和分页，而不是直接把 false 改回 true 掩盖问题。

原生预处理不生效时按属性和 SQL 边界排查

排查顺序可以固定成“驱动—属性—语句边界—异常”。先看可用驱动，再回读模拟开关；如果属性是 false，它表示“尝试原生”，并不承诺每一种 SQL 都由服务器原生准备。随后检查占位符是否只用于值，以及同一命名占位符是否被重复使用；为了兼容不同驱动，重复位置最好改成不同占位符。

getAttribute(PDO::ATTR_EMULATE_PREPARES);
if ($emulated === true) {
    throw new RuntimeException('当前连接仍在使用模拟预处理');
}
?>

最容易踩坑的是下面这种写法：SELECT * FROM :table。占位符只能绑定值，不能替换表名、列名、关键字或 ASC/DESC。这类动态结构应使用固定白名单映射，例如把 email 映射到预先写好的 SQL 片段；不要把原始请求参数直接拼进查询。

兼容性、性能和安全边界

原生预处理的价值在于把 SQL 结构和参数值分开，并让服务器端/驱动端按其能力处理准备与执行；它不是所有语句、所有驱动都具有完全相同的行为。遇到失败时保留 PDOException 的 SQLSTATE、错误码和脱敏后的查询上下文，修正具体语句边界。连接池、字符集、事务和索引问题也不要混同为预处理问题。

性能上，是否复用 prepared statement 要看实际调用次数和驱动行为，不要仅凭“原生”二字推断一定更快。安全上，账号密码从环境配置读取，异常日志脱敏；动态表名、列名和排序字段走白名单，值走 bindValue 或 execute 参数。

常见问题

PDO::ATTR_EMULATE_PREPARES 设置为 false 后就绝对是原生吗？

不是。它表示 PDO 优先尝试原生预处理；如果当前驱动无法成功准备该语句，仍可能回退到模拟方式，所以还要检查具体 SQL 和驱动能力。

为什么表名不能写成 PDO 占位符？

占位符用于值，不用于 SQL 语法结构。表名和列名应从固定白名单映射，不能直接拼接用户输入。

只调用 getAttribute 就能证明查询使用了服务器预处理吗？

不能。它只能确认连接级属性的意图；最终行为还受驱动、语句形态和兼容性影响。排查时应结合异常信息和最小可复现 SQL。