TypeScript路径别名配置下Knex迁移报错找不到模块的解决求助

核心原因 #

ts-node 默认不会解析 tsconfig 中的 paths 别名配置，而 Knex 迁移依赖 ts-node 运行 TypeScript 文件，因此需要额外配置让 ts-node 识别路径别名。

解决方案 #

1. 安装依赖并调整运行命令 #

首先安装 tsconfig-paths，它能让 ts-node 读取 tsconfig 的路径别名配置：

npm install tsconfig-paths --save-dev

然后修改迁移命令，添加 tsconfig-paths/register 启用路径解析：

# 使用主 tsconfig.json 的情况
TS_NODE_PROJECT=tsconfig.json node -r ts-node/register -r tsconfig-paths/register ./node_modules/knex/bin/cli.js migrate:latest

# yarn 用户可使用
TS_NODE_PROJECT=tsconfig.json yarn knex migrate:latest -r tsconfig-paths/register

2. 补全 tsconfig 关键配置 #

你的 tsconfig.json 必须包含 baseUrl（paths 依赖此配置），补充后示例如下：

{
  "compilerOptions": {
    "baseUrl": "./", // 必须添加，路径别名基于此目录
    "paths": {
      "@foo-alias/*": ["src/foo/*"]
    },
    // 其他编译选项...
  },
  "exclude": ["node_modules"]
}

3. 使用 Knex 专用 tsconfig（推荐） #

如果主 tsconfig 使用 ESModule 规范（"module": "ESNext"），Knex CLI 可能出现兼容问题，建议创建 tsconfig.knexfile.json 继承主配置并调整模块规范：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS", // Knex CLI 需要 CommonJS 模块
    "outDir": "./dist" // 可选，确保输出目录正确
  },
  "include": ["knexfile.ts", "src/**/*.ts", "migrations/**/*.ts"]
}

对应的迁移命令改为：

TS_NODE_PROJECT=tsconfig.knexfile.json node -r ts-node/register -r tsconfig-paths/register ./node_modules/knex/bin/cli.js migrate:latest

4. 手动映射别名（无额外依赖方案） #

若不想安装 tsconfig-paths，可在 knexfile.ts 开头手动添加别名解析：

import { resolve } from 'path';
import { addAlias } from 'module-alias';

// 手动映射别名
addAlias('@foo-alias', resolve(__dirname, 'src/foo'));

// 后续 Knex 配置代码...

这种方式需先安装 module-alias：

npm install module-alias --save-dev

内容的提问来源于stack exchange，提问作者S. C.