TypeScript ESM项目Jest测试导入Knex类型报错问题排查

问题背景 #

我维护一个采用ESM规范的TypeScript项目，已配置ts-jest实现ESM转换以运行Jest测试，但执行测试时持续抛出错误：

The requested module 'knex' does not provide an export named 'Knex'

该Knex类型主要用于Inversify依赖注入，示例代码如下：

class RepositoryClass {
 constructor(@inject(Types.DbConnectionOne) connection: Knex) {
    super(connection);
  }
}

现有Jest配置 #

{
  "preset": "ts-jest/presets/default-esm",
  "testEnvironment": "node",
  "clearMocks": true,
  "collectCoverage": false,
  "coverageDirectory": "coverage",
  "workerIdleMemoryLimit": "512MB",
  "collectCoverageFrom": ["./src/**/*", "!./src/**/*.test.ts"],
  "coveragePathIgnorePatterns": [],
  "coverageProvider": "v8",
  "coverageReporters": ["json", "lcov", "text", "clover", "cobertura"],
  "setupFiles": ["<rootDir>jest.bootstrap.ts"],
  "testPathIgnorePatterns": ["/node_modules/", "/.build/", "/config/"],
  "transform": {
    ".(ts|tsx)": ["ts-jest", { "useESM": true }]
  },
  "moduleNameMapper": {
    "@/(.*)": "<rootDir>/src/$1",
    "@tests/(.*)": "<rootDir>/tests/$1"
  },
  "transformIgnorePatterns": ["/node_modules/", "\\.pnp\\.[^\\/]+$"],
  "verbose": true,
  "extensionsToTreatAsEsm": [".ts"]
}

已尝试的解决方案 #

• 最初使用import { Knex } from 'knex';导入类型定义
• 了解ESM处理CJS模块命名导出的兼容性问题后，尝试import knex from 'knex'并引用knex.Knex，但该属性不存在
• 尝试社区推荐的import knex, { Knex } from 'knex'语法，依旧无法找到命名导出

补充排查信息 #

移除依赖Inversify的文件中的常规命名导入，仅保留import type { Knex } from 'knex'时，测试能够正常运行，初步怀疑报错与Inversify的运行时处理逻辑相关。

可行解决建议 #

1. 强制类型导入使用type断言 #

Knex是TypeScript类型而非运行时值，在ESM环境下必须明确标记为类型导入，避免被转译为运行时执行的导入语句。确保所有引用Knex的地方都使用类型导入：

import type { Knex } from 'knex';

尤其在Inversify装饰器中，装饰器会在运行时执行，错误的非类型导入会触发运行时的导出查找逻辑。

2. 调整ts-jest的CJS模块处理规则 #

Knex本身是CommonJS模块，ESM环境下直接导入可能存在兼容性问题。修改transformIgnorePatterns，让ts-jest处理knex模块：

"transformIgnorePatterns": ["/node_modules/(?!knex)/", "\\.pnp\\.[^\\/]+$"]

这样ts-jest会转换knex模块，确保ESM环境能正确解析其导出。

3. 隔离Inversify的类型与运行时逻辑 #

Inversify的依赖注入可能会误将类型引用当作运行时值处理。可以：

• 使用字符串或Symbol作为注入token，而非直接依赖类型
• 确保类型仅在类型注解中使用，不参与任何运行时的装饰器参数或逻辑

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