本文详解在 Express + Knex + SQLite 环境下，通过 onConflict().ignore() 实现按业务字段（如 name）去重插入的完整方案，重点解决因缺失数据库层 UNIQUE 约束导致的 SQLITE_CONSTRAINT 错误。
本文详解在 express + knex + sqlite 环境下，通过 `onconflict().ignore()` 实现按业务字段（如 `name`）去重插入的完整方案，重点解决因缺失数据库层 unique 约束导致的 `sqlite_constraint` 错误。
在使用 Knex 向 SQLite 插入一批练习题（exercisesDB 表）时，你希望仅当 name 字段尚未存在时才插入新记录——这看似只需 .onConflict('name').ignore() 即可实现，但实际却报错：
SQLITE_CONSTRAINT: UNIQUE constraint failed: exercisesDB.id
该错误的根本原因并非 Knex 的 Bug，而是 SQLite 层未对 name 字段建立 UNIQUE 约束。Knex 的 onConflict() 在 SQLite（及 PostgreSQL）中要求：被指定为冲突目标的列，必须是主键（PRIMARY KEY）或已显式声明为 UNIQUE 的索引列；否则，Knex 会回退到检查表的主键（通常是自增 id），而你未提供 id 值，导致插入时触发主键冲突。
✅ 正确做法分三步：
1. 确保数据库 Schema 已添加 UNIQUE 约束
在建表或迁移脚本中，必须显式为 name 字段添加唯一索引。例如，使用 Knex 迁移文件：
// migrations/20240101_create_exercises_table.js
exports.up = async (knex) => {
await knex.schema.createTable('exercisesDB', (table) => {
table.increments('id').primary();
table.string('name').notNullable();
table.text('description');
table.timestamps(true, true);
});
// ✅ 关键：为 name 添加唯一索引（SQLite 要求）
await knex.schema.raw('CREATE UNIQUE INDEX idx_exercises_name ON exercisesDB(name)');
};
exports.down = async (knex) => {
await knex.schema.dropTableIfExists('exercisesDB');
await knex.schema.raw('DROP INDEX IF EXISTS idx_exercises_name');
};
⚠️ 注意：SQLite 不支持 ALTER TABLE ... ADD CONSTRAINT UNIQUE(...) 语法，因此必须用 CREATE UNIQUE INDEX 显式创建；若表已存在，需先执行该语句再运行插入逻辑。
2. 使用 onConflict().ignore() 批量插入（推荐：单次 insert() + 数组）
避免在事务中循环多次 insert()（性能差、易出错），应将数组整体传入，并确保 onConflict 指向已建索引的字段：
// ✅ 高效且安全的写法
try {
const result = await knex.transaction(async (trx) => {
return await trx('exercisesDB')
.insert(exercisesToAdd) // exercisesToAdd 是对象数组
.onConflict('name') // 必须与 UNIQUE 索引字段完全一致
.ignore();
});
console.log(`成功插入 ${result.length} 条记录（跳过已存在 name）`);
} catch (err) {
console.error('事务失败:', err.message);
throw err;
}
? 提示：onConflict('name') 在 SQLite 中等价于 ON CONFLICT(name) DO NOTHING，前提是 name 有 UNIQUE 索引。Knex 不会自动创建该索引，必须由开发者保障。
3. 替代方案：onConflict().merge()（如需更新部分字段）
若希望 name 存在时更新 description 或时间戳，可改用 merge()：
await knex('exercisesDB')
.insert(exercisesToAdd)
.onConflict('name')
.merge(['description', 'updated_at']); // 仅更新指定字段
❗常见误区与注意事项
- ❌ 不要手动 trx.commit() / trx.rollback() 在 .then().catch() 中调用 —— Knex 事务会自动根据 Promise 状态提交或回滚；显式调用会导致 Transaction already completed 错误。
- ❌ 不要依赖 id 主键做业务去重 —— id 是自增主键，无法表达业务唯一性。
- ✅ 建议在应用启动时校验约束是否存在（尤其开发/测试环境），可用 knex.schema.hasColumn() + 自定义查询辅助验证索引。
- ✅ 生产部署前务必运行迁移，确保 CREATE UNIQUE INDEX 已生效（可通过 SQLite CLI 执行 .indices exercisesDB 验证）。
掌握这一模式后，你即可在 Express API 中安全地实现“存在即跳过”的幂等插入逻辑，兼顾性能、健壮性与可维护性。
