UPDATE 报 Duplicate entry 错误实为 INSERT … ON DUPLICATE KEY UPDATE 触发，因唯一键（主键/联合唯一索引）冲突所致；常见于 ORM 的 upsert 类方法、WHERE 条件未覆盖唯一字段或存在多唯一索引。
UPDATE 报 Duplicate entry 错误，其实是 INSERT … ON DUPLICATE KEY UPDATE 用错了
MySQL 的 UPDATE 本身不会因为主键冲突报 Duplicate entry —— 这个错误只出现在插入类操作中。如果你在执行 UPDATE 时看到这个报错，大概率是代码里实际执行的是 INSERT ... ON DUPLICATE KEY UPDATE，或者 ORM 自动生成了带插入语义的语句。
常见诱因：
- 使用了 Laravel 的
upsert()、Django 的update_or_create()、SQLAlchemy 的merge() - 手写 SQL 混用了
INSERT和ON DUPLICATE KEY UPDATE，但 WHERE 条件没兜住唯一键 - 表里有多个唯一索引（比如
UNIQUE(email)+UNIQUE(phone)），而你试图更新一条 email 已存在、但 phone 冲突的记录
WHERE 条件漏掉唯一键字段，导致 UPDATE 变成“多行匹配+重复插入”
当 UPDATE 的 WHERE 条件不包含任何唯一约束字段（如主键或唯一索引列），又恰好配合了触发器、自增主键或某些 ORM 的“先查后插”逻辑，就可能绕过校验直接走到插入分支。
实操建议：
- 检查你的
UPDATE语句是否真的只影响一行：加LIMIT 1测试（仅调试用，生产慎用） - 用
EXPLAIN看执行计划，确认key列是否命中了主键或唯一索引 - 如果业务上本该只改某 ID 的记录，
WHERE id = ?必须显式写出，不能靠其他字段“推断” - 避免用非唯一字段（如
name、status）做UPDATE的主条件，除非你知道它在当前数据下恰好唯一
唯一索引不止主键，联合唯一索引也会计入冲突判断
很多人只盯着 PRIMARY KEY，却忽略了 UNIQUE KEY (user_id, category) 这类联合索引。当你执行 INSERT ... ON DUPLICATE KEY UPDATE 时，只要任意一个唯一索引冲突，就会报错。
排查方法：
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录，或需要将该能力封装成可公开复用的 Codex skill。
- 运行
SHOW CREATE TABLE `your_table`;，逐行看所有UNIQUE KEY定义 - 检查你要插入/更新的值，是否无意中复用了已有组合（例如：同一
user_id下两次插入category = 'report'） - 如果业务允许覆盖，确保
ON DUPLICATE KEY UPDATE显式列出所有要更新的字段，而不是留空
用 SELECT + UPDATE 替代 INSERT … ON DUPLICATE KEY UPDATE 更可控
当冲突逻辑复杂（比如要根据旧值计算新值、或需要判断是否真有变更），硬塞进 ON DUPLICATE KEY UPDATE 容易出错。这时候分两步更稳妥。
示例场景：给用户积分 +10，但只在当前积分
SELECT points FROM users WHERE id = 123;
拿到结果后，在应用层判断：if points
优点：
- 逻辑清晰，条件判断不依赖 MySQL 表达式能力
- 避免
VALUES(points)在冲突分支中取到旧值还是新值的歧义 - 方便加锁（如
SELECT ... FOR UPDATE）防止并发覆盖
代价是多一次往返，但比修复一次线上数据错乱便宜得多。
真正麻烦的不是语法写错，而是把“唯一性”当成数据库的自动兜底机制，而没在业务层确认这条记录到底该不该存在、以什么方式存在。
