当 Knex 未显式传入配置即直接调用（如 knex('table')），它会回退到默认的 sqlite3 客户端，从而报错“Cannot find module 'sqlite3'”——即使项目已正确配置 MySQL2。根本原因是未基于 knexfile.ts 初始化实例。
当 knex 未显式传入配置即直接调用（如 `knex('table')`），它会回退到默认的 `sqlite3` 客户端，从而报错“cannot find module 'sqlite3'”——即使项目已正确配置 mysql2。根本原因是未基于 `knexfile.ts` 初始化实例。
在 Node.js + TypeScript 项目中使用 Knex 时，import knex from 'knex' 仅导入了 Knex 构造函数，并不等于一个已配置的数据库实例。若直接调用 knex('users').insert(...)，Knex 会使用内置默认配置（客户端为 sqlite3，内存数据库路径为 :memory:），此时即使项目中从未安装 sqlite3，也会触发模块加载失败错误。
正确做法是：显式读取并传入 knexfile.ts 中导出的配置，创建一个专属的、已绑定 MySQL2 的 Knex 实例。注意以下关键点：
✅ 正确导入配置：knexfile.ts 使用 module.exports = config 导出，TypeScript 项目需通过 import { config } from './knexfile'（相对路径）或配置 tsconfig.json 的 baseUrl/paths 支持别名导入。避免使用 import config from 'knexfile'（CommonJS 默认导出不兼容 ESM 默认导入）。
✅ 单例复用实例：应在模块顶层创建一次 Knex 实例（如 const db = knex(config.development)），并在路由/服务中复用该实例，而非每次请求都新建——既避免重复连接开销，也确保配置生效。
✅ 环境适配（推荐）：生产环境应读取 process.env.NODE_ENV 动态选择配置项，例如：
import { config } from './knexfile';
import knex from 'knex';
const env = process.env.NODE_ENV || 'development';
const db = knex(config[env]);
? 完整修复示例（root.ts）：
import { FastifyPluginAsync } from 'fastify';
import knex from 'knex';
import { config } from './knexfile'; // ✅ 使用相对路径确保正确解析
// 创建已配置的 Knex 实例（MySQL2）
const db = knex(config.development);
const root: FastifyPluginAsync = async (fastify, opts): Promise<void> => {
fastify.post('/create', async (request, reply) => {
try {
await db('users').insert(request.body);
return { message: 'User created', data: request.body };
} catch (err) {
fastify.log.error(err);
throw err;
}
});
};
export default root;</void>
⚠️ 注意事项：
- 若使用 ES Module（
.mjs或type: "module"），需将knexfile.ts改为knexfile.mjs并使用export default config，否则 CommonJS 的module.exports不被原生支持； - 生产部署时务必校验
NODE_ENV环境变量与knexfile.ts中配置键一致； - 建议在应用启动时执行
db.raw('SELECT 1')健康检查，提前暴露连接问题； - 避免在多个文件中重复
knex(config)—— 应统一导出db实例供全局依赖注入（如 Fastify 的decorate）。
遵循此模式，Knex 将严格使用 mysql2 驱动，彻底规避 sqlite3 相关错误。
