Node.js 14.x ESM环境下Knex迁移报缺少client配置错误排查

• 核心矛盾在于Knex CLI的ESM加载规则和你当前的knexfile导出结构不匹配：
  • Knex CLI在读取knexfile.js时，会优先查找文件默认导出的环境配置映射对象（即各个环境为键的配置集合），用来生成迁移专用的独立Knex实例
  • 你当前的knexfile仅导出了一个提前初始化好的Knex连接实例（database），CLI解析不到符合格式的配置集合，最终拿到的配置为空值，初始化时自然找不到client字段触发报错
• 两个叠加的兼容性问题放大了故障表现：
  • 你使用的Knex 0.21.18是较早提供ESM支持的版本，对导出格式的校验非常严格，不会自动兼容“导出实例而非配置”的写法
  • Node 14的ESM运行时没有内置__dirname全局变量，你配置里直接引用__dirname原本就会触发运行错误，只是因为CLI没正确解析文件导出，这个错误被静默吞掉，最终只抛出找不到client的表层报错

1. 调整knexfile的导出逻辑 #

将纯配置对象作为文件的默认导出（满足CLI的加载要求），保留业务代码需要的Knex实例导出，同时补上ESM环境下的路径兼容：

import dotenv from "dotenv";
import knex from "knex";
import path from "path";
import { fileURLToPath } from "url";

// 补全ESM环境下的__dirname等价实现
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

dotenv.config();

const config = {
  sandbox: {
    client: "sqlite3",
    connection: {
      filename: "./sandbox.sqlite3",
    },
    debug: true,
    migrations: {
      directory: path.join(__dirname, "migrations"),
      tableName: "knex_schema_history",
    },
    seeds: {
      directory: path.join(__dirname, "seeds", "sandbox"),
    },
    useNullAsDefault: true,
  },
};

// 默认导出纯配置对象，供Knex CLI加载
export default config;
// 业务代码需要的实例化Knex对象单独导出即可，不影响CLI解析
export const database = knex(config[process.env.NODE_ENV]);

2. 执行迁移时显式指定环境 #

避免依赖dotenv的隐式环境加载导致配置匹配失效，执行命令时直接传--env参数指定要使用的配置：

npx knex --esm migrate:latest --env sandbox

• 你当前使用的Knex 0.21.x版本的ESM支持属于实验特性，迁移执行过程中如果遇到其他加载类异常，优先确认当前运行的Node版本为14.x，不要跨大版本升级Node触发不兼容问题
• 业务代码中Objection.js绑定Knex实例的逻辑不受本次结构调整影响，正常导入database实例使用即可

内容的提问来源于stack exchange，提问作者user4695271