PostgreSQL下使用Knex.js批量插入时忽略重复数据的方法

安全阿岳

2026-7-16

在Knex.js中用批量插入忽略重复数据的解决方案

Knex的batchInsert方法本身不支持链式调用onConflict，因为它返回的是RawQueryBuilder，和常规insert返回的QueryBuilderAPI逻辑不同，这就是你遇到报错的核心原因。下面提供两种可行的替代方案：

方案一：用常规`insert`传入数据数组（推荐，简单直接）

常规insert方法支持直接传入数据数组，同时可以正常链式调用onConflict和ignore()，Knex会自动生成一条包含多行值的INSERT语句，并带上冲突处理逻辑：

const newUsers = await knex('user')
  .insert(filteredUsers)
  .onConflict('userId') // 指定用于判断重复的唯一约束字段
  .ignore()
  .returning('email');

注意事项

如果你的数据量极大（比如超过1万条），这条SQL语句可能会超过数据库允许的最大长度限制。这时可以手动把filteredUsers分成多个小批次（比如每1000条一组），循环执行上面的代码即可。

方案二：手动构建Raw SQL查询

如果需要严格按固定批次执行插入，或者要做更精细的SQL控制，可以用knex.raw直接编写包含冲突处理的批量插入语句：

// 定义要插入的字段列表（需和数据顺序对应）
const columns = ['userId', 'email', 'name'];
// 将数据转换为二维数组，匹配字段顺序
const values = filteredUsers.map(user => [user.userId, user.email, user.name]);

const result = await knex.raw(
  `INSERT INTO user (??) VALUES ? ON CONFLICT ("userId") DO NOTHING RETURNING "email"`,
  [columns, values]
);
// 从查询结果中提取返回的email列表
const newUsers = result.rows;

这里用??安全处理列名（避免SQL注入），?会自动把二维数组转换成(val1,val2),(val3,val4)...的格式，完美适配批量插入场景。