SQLSTATE[21S01]错误主因是insertAll每行字段数不一致，即使数据库允许NULL或默认值也必须严格对齐；常见于混用关联/索引键、漏填非空字段，需用array_map('count', $dataList)校验并统一初始化模板。
ThinkPHP批量添加数据时出现SQLSTATE报错，绝大多数情况不是语法写错，而是字段结构、主键状态或连接上下文没对齐——得先看报错码末尾数字，再动手改代码。
SQLSTATE[21S01]：insertAll字段数量不一致
这是最常被忽略的“隐形坑”：insertAll()要求每行数据的键名数量必须严格一致，哪怕数据库字段允许NULL或有默认值，也不能少填一个字段。
- 错误现象：
SQLSTATE[21S01]: Insert value list does not match column list: 1136 Column count doesn't match value count at row 2，说明第二行开始字段数就对不上 - 常见原因：数组里混用了关联键（如
['name' => 'a']）和索引键（如['a']），或某行漏了status、created_at等非空但无默认值的字段 - 实操建议：
用array_map('count', $dataList)快速检查每行字段数是否全等；
统一用array_fill_keys(['name', 'email', 'status'], null)初始化模板，再逐行赋值；
避免从$_POST直接取值拼数组，中间可能丢键
SQLSTATE[23000]：save()复用实例导致主键冲突
同一个模型实例反复调用save()，TP会把第一次插入生成的id带进后续操作，第二次就变成UPDATE，若表无该ID则报主键冲突。
- 错误现象：
SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '86' for key 'PRIMARY' - 根本原因：
$user = new User后，第一次$user->save()成功，TP自动把自增ID写入实例内部；第二次$user->save()仍带这个ID，触发UPDATE而非INSERT - 实操建议：
批量新增必须每次新建实例：(new User)->save($data)；
或强制重置为新增模式：$user->data($data, true)->isUpdate(false)->save()；
别信$user->id = null，它不生效；必须用$user->data('id', null)清掉内部缓存值
SQLSTATE[HY000]：字符集/排序规则引发的隐性失败
看起来是插入失败，实际是MySQL在执行INSERT前做隐式类型转换或JOIN校验时，因collation不一致直接拒掉整条SQL——尤其发生在含中文、emoji或跨表关联字段时。
立即学习“PHP免费学习笔记（深入）”；
- 典型报错：
SQLSTATE[HY000] [1267] Illegal mix of collations，但你可能只看到笼统的General error - 排查路径：
查表字段collation：SHOW FULL COLUMNS FROM user，确认name和email字段是否都为utf8mb4_unicode_ci；
查连接层设置：Db::execute("SHOW VARIABLES LIKE 'collation%';")，确保collation_connection与字段一致；
DSN中必须显式写charset=utf8mb4，config里的charset配置在新版TP中已失效 - 注意点：即使所有字段都是
utf8mb4，只要一个是utf8mb4_0900_ai_ci、另一个是utf8mb4_unicode_ci，也会触发1267
SQLSTATE[2006]或[HY000]：长事务/空闲连接中断导致批量中途失败
insertAll()本质是单条INSERT语句（含多VALUES），但如果数据量大、执行时间长，或连接已空闲超wait_timeout，MySQL会在中间断开，TP抛出MySQL server has gone away，而你只看到General error。
- 验证方式：
SHOW STATUS LIKE 'Threads_connected'看连接数是否飙升；SHOW PROCESSLIST找大量Sleep状态连接 - 临时解法：
在database.php的params中加PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION和'break_reconnect' => true；
但注意：CLI队列任务中开启break_reconnect可能导致事务丢失，应仅在Web请求中启用 - 根治办法：
拆分大数据集，每50–100条一批调用insertAll()；
避免在事务内执行大批量insertAll，改用原生INSERT ... SELECT或临时表导入
批量插入真正难的不是写法，而是字段对齐、连接生命周期和字符集这三层隐性约束——任何一个没卡准，SQLSTATE就会给你一个模糊报错，让你在日志里翻半小时。
