ERROR 1064是MySQL解析阶段语法错误，根源90%在报错末尾“near 'xxx'”处：xxx多为保留字（如order、user）、未引号字符串、版本不兼容语法或未转义特殊字符，须加反引号、补单引号、查版本手册或转义处理。
Hyperf 应用里通过携程 MySQL 客户端（如 hyperf/database 或基于 pdo_mysql 的封装）执行 SQL 报错时，ERROR 1064 这类语法错误不会直接暴露在业务日志里——它被 PDO 层吞掉一部分上下文，只留下模糊的“SQLSTATE[42000]”或“PDOException”，真正线索藏在底层报错位置和原始 SQL 构造过程里。
查 Hyerf 日志里有没有完整 SQL 和 near 提示
默认情况下，Hyperf 的 Db::statement() 或 Db::select() 出错时，Exception 的 getMessage() 可能只显示“SQLSTATE[42000]”，不带 near 内容。必须确认是否启用了 PDO 的 ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION，且日志配置没截断异常堆栈：
- 检查
config/autoload/db.php中'options' => [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]是否存在 - 在
ExceptionHandler里打印$throwable->getTraceAsString()，看 PDO 构造的 SQL 是否被记录 - 若用
Db::raw()拼接变量，echo $sql或var_dump($sql)打印前必须加try/catch，否则异常中断导致看不到输出
还原原始 SQL：别信日志里拼出来的字符串
Hyperf 默认对参数做预处理（prepare/execute），但语法错误只发生在 prepare() 阶段——也就是说，出错的不是绑定后的语句，而是你传给 Db::select() 的那个含占位符的模板 SQL。常见陷阱：
-
Db::select("SELECT * FROM user WHERE name = ?", [$name])不会报语法错，因为 ? 被 PDO 替换后才执行；但Db::select("SELECT * FROM user WHERE name = '$name'")（字符串拼接）会直接报ERROR 1064，尤其当$name为空或含单引号时 - 用
Db::table('user')->where('name', $name)->get()看似安全，但如果$name是数组或对象，Hyperf 生成的 SQL 可能漏括号或关键字，比如变成WHERE name = Array - 日志里看到的
SQLSTATE[42000]对应的原始 SQL，要从Exception的getPrevious()或PDOException::$errorInfo里取，不是从getMessage()直接截
定位 near 位置：用 mysql 命令行复现
Hyperf 日志里的行号毫无意义——那是 PHP 文件的行号，不是 SQL 的逻辑行。真正要做的，是把日志中还原出的原始 SQL（不含 PHP 变量）复制到本地 mysql 客户端执行：
- 先运行
mysql --no-auto-rehash --force -e "source /dev/stdin"，然后粘贴 SQL，--force会输出比 PHP 更细的卡点位置 - 如果 SQL 含反引号或保留字（如
order、rank），注意 Hyperf 默认不自动加反引号，得手动补全：SELECT `order` FROM `user` - 特别检查 JSON 函数写法：
JSON_EXTRACT(data, '$.id')在 MySQL 5.7+ 才支持，若写成JSON_EXTRACT(data, @path)，mysql会报near '@path'，而 Hyperf 日志里只显示“语法错误”
携程客户端特有坑：SQL 注入防护机制干扰语法校验
部分内部封装的携程 MySQL 客户端（如基于 ctrip-db 的定制版）会在执行前做 SQL 白名单校验或关键字过滤，这会导致：
- 合法 SQL 被误判为风险语句（如含
UNION SELECT即使是子查询），抛出非标准错误码（如ERROR 9999），而非1064 - 自动重写 SQL：把
INSERT INTO t VALUES (1, 'a')改成INSERT IGNORE INTO t VALUES (1, 'a')，但改写逻辑有 bug 时可能漏括号 - 解决方案：临时绕过封装，用原生
PDO实例执行同一段 SQL，对比错误信息是否一致；若不一致，说明是客户端层拦截，需查内部文档或联系基础架构组
最易被忽略的是：Hyperf 的 Db 组件默认开启 strict 模式，但某些携程定制客户端会关闭它，导致本该报错的模糊语法（如隐式类型转换）在开发环境不报，在生产 MySQL 8.0 上突然失败——定位时得确认两边的 sql_mode 是否一致。
