knex.js 的 `batchinsert` 工具函数不支持 `.onconflict()` 链式调用；需手动分块 + 事务 + 单次 `insert().onconflict().ignore()` 组合实现批量去重插入。
在 postgresql 中使用 Knex.js 进行高效、安全的批量插入并自动忽略重复记录（如基于 userId 或 email 唯一键冲突），是常见但易踩坑的需求。遗憾的是，Knex 提供的 .batchInsert() 是一个纯工具型辅助方法（源码见 batch-insert.js），它仅负责将大数组切片、分批调用 .insert() 并合并结果，不支持链式调用 .onConflict()、.ignore() 等冲突处理方法——这也是你直接链式调用 .onConflict(‘userId’).ignore() 无效的根本原因。
✅ 正确做法是：手动分块 + 显式事务 + 每批调用带冲突处理的 insert()。以下为生产就绪的实现示例：
import { chunk } from 'lodash'; import knex from './knex'; // 你的 Knex 实例 interface User { userId: string; email: string; name: string; } const batchInsertIgnoreOnConflict = async ( tableName: string, users: User[], chunkSize: number = 1000 ): Promise => { const chunks = chunk(users, chunkSize); const allInsertedEmails: string[] = []; await knex.transaction(async (trx) => { for (const chunk of chunks) { const emails = await trx(tableName) .insert(chunk) .returning('email') // 注意：PostgreSQL 要求 RETURNING 字段存在且可返回 .onConflict('userId') // 指定唯一约束字段（需确保该列有 UNIQUE 索引） .ignore(); allInsertedEmails.push(...emails.map(u => u.email)); } }); return allInsertedEmails; }; // 使用示例 const filteredUsers: User[] = [ { userId: 'u1', email: 'a@example.com', name: 'Alice' }, { userId: 'u2', email: 'b@example.com', name: 'Bob' }, // ... 更多用户 ]; const insertedEmails = await batchInsertIgnoreOnConflict('user', filteredUsers, 1000); console.log(`成功插入 ${insertedEmails.length} 条新记录`); ⚠️ 关键注意事项：
- 唯一索引前提：.onConflict(‘userId’) 要求数据库中 userId 列已建 UNIQUE 索引（或主键），否则 PostgreSQL 将报错 there is no unique or exclusion constraint matching the ON CONFLICT specification。
- returning 兼容性：PostgreSQL 支持 RETURNING，但 mysql / sqlite 不支持；若需跨数据库兼容，请移除 .returning() 或做条件判断。
- 事务安全性：所有批次在单个事务中执行，任一批次失败将回滚全部操作，保障数据一致性。
- 性能权衡：chunkSize = 1000 是较优平衡点（避免单条 SQL 过长，也减少网络往返）；可根据实际行宽与内存调整，但建议 ≤ 5000。
- 类型提示：typescript 用户请确保泛型
与表结构一致，并启用 returning 类型推导（Knex v2+ 支持）。
总结：不要试图给 .batchInsert() “打补丁”，而应拥抱 Knex 的底层灵活性——用 knex.transaction() + lodash.chunk + insert().onConflict().ignore() 构建可控、可维护、符合 PostgreSQL 语义的批量去重插入逻辑。