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<string[]> => {
const chunks = chunk(users, chunkSize);
const allInsertedEmails: string[] = [];
await knex.transaction(async (trx) => {
for (const chunk of chunks) {
const emails = await trx<User>(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 语义的批量去重插入逻辑。
