QueryException 报错应先检查 SQL 和字段名是否匹配，核心线索在异常 message 中，如“Unknown column 'user_name'”表明模型与数据库字段名不一致，需核对迁移文件、模型 $schema、表结构及大小写。
QueryException 报错时先看 SQL 和字段名是否匹配
ThinkPHP 的 QueryException 多数不是框架 bug，而是 SQL 执行失败后抛出的包装异常。真正线索藏在异常 message 里，比如 SQLSTATE[42S22]: Column not found: 1054 Unknown column 'user_name' in 'field list' —— 这说明模型里写了 user_name，但数据库表实际字段是 username 或 name。
常见踩坑点：
- 迁移文件里用
->string('user_name')建了字段，但模型中$fillable或protected $schema写成'username'（少下划线） - 数据库已存在表，手动改过字段名，但没同步更新迁移文件或模型的
$schema - 使用
Db::table()时拼 SQL 字符串，变量名和字段名混用，比如写成"WHERE name = '{$data['user_name']}'"，而表里根本没有user_name
迁移文件执行后字段没生效？检查 migrate:status 和表结构实际状态
运行 php think migrate:run 成功不代表字段真加进去了。尤其在多环境（本地/测试/生产）或多人协作时，migrate:status 显示“Ran”，但数据库里查不到字段，大概率是迁移类中的 up() 方法没真正执行 ALTER 操作。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
php think migrate:status确认目标迁移是否标记为 R（Ran），再手动连数据库执行DESCRIBE users;对比字段 - 迁移类中避免写条件判断跳过操作，比如
if ($this->connection->getDriver() === 'mysql') { ... }—— 这会导致 SQLite 环境下字段缺失却无报错 - 不要在
up()里调用模型方法（如UserModel::create()），迁移应只管结构，数据初始化放 seed 或命令行脚本里
模型中 $schema 或 $type 映射错误导致 QueryException
ThinkPHP 6.1+ 支持在模型里声明 protected $schema 和 protected $type 来显式定义字段类型和映射。一旦写错，比如把 created_at 的类型写成 'integer' 而数据库是 DATETIME，插入时就会触发 QueryException，提示类型不匹配或截断警告。
关键细节：
-
$schema中的键必须和数据库字段名完全一致（包括大小写、下划线），不能写成驼峰；$type中的键也必须是真实字段名，不是模型属性名 - 如果用了软删除，
delete_time字段必须在$schema中声明为'datetime'或'timestamp'，否则查询时会因类型转换失败报错 - 字段有默认值（如
status tinyint(1) DEFAULT 1），但$schema没声明，某些场景下 ORM 会传null进去，触发 NOT NULL 约束异常
调试 QueryException 必须打开 PDO 异常模式和日志
默认情况下 ThinkPHP 只抛出 QueryException，不显示原始 SQL 和绑定参数，导致你只能靠猜。必须主动开启底层调试能力。
两步到位：
- 在
config/database.php中确保'deploy' => 0（非部署模式），并设置'debug' => true - 在
app/middleware.php或全局中间件中临时加一句：\think\PDO::setDebug(true);，这样异常堆栈里会出现完整 SQL 和参数数组 - 别依赖
getLastSql()—— 它只返回最后一条，而QueryException往往来自事务中某条中间 SQL，得看异常对象里的$e->getSql()和$e->getBind()
最常被忽略的是：字段映射问题往往在关联查询或自动时间戳触发时才暴露，单测某个 save() 没问题，一跑带 with() 的列表就崩 —— 所以排查一定要复现完整请求链路，不能只盯单个模型操作。
