Cypress配置文件无效：导入TS文件触发.ts扩展名未知错误

问题分析 #

你碰到的错误提示如下：

Your configFile is invalid: /home/project/cypress.config.ts TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /home/project/cypress.config.ts

核心原因是Node.js默认无法直接处理TypeScript文件的导入逻辑——尽管Cypress支持.ts格式的配置文件，但当你在配置文件里导入外部TS模块时，Node.js的模块加载器无法识别.ts扩展名，从而触发报错。

解决方案 #

1. 用ts-node处理TS文件导入 #

先安装依赖：

npm install -D ts-node typescript

修改启动命令，指定用ts-node加载配置文件：

npx cypress open --config-file ./cypress.config.ts -r ts-node/register

或者在package.json里添加脚本简化操作：

{
  "scripts": {
    "cypress:open": "cypress open --config-file ./cypress.config.ts -r ts-node/register"
  }
}

之后运行npm run cypress:open即可启动。

2. 调整tsconfig.json配置 #

确保你的tsconfig.json包含以下关键设置，让Node.js能正确解析TS模块：

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES2019",
    "esModuleInterop": true,
    "moduleResolution": "node",
    "resolveJsonModule": true
  },
  "include": [
    "cypress.config.ts",
    "src/server/db/**/*"
  ]
}

注意module设为CommonJS（Node.js默认模块系统），include要覆盖你导入的TS文件路径。

3. 用动态导入替代静态导入 #

在cypress.config.ts里使用异步动态导入，Cypress的setupNodeEvents支持异步函数：

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    async setupNodeEvents(on, config) {
      // 动态导入TS模块
      const db = await import('./src/server/db/datasource');
      // 注册自定义任务
      on('task', {
        async queryDatabase(query) {
          return await db.default.query(query);
        }
      });
      return config;
    },
  },
});

这种方式不需要额外依赖，利用ES模块的动态导入特性绕开Node.js静态导入的限制。

4. 检查导入路径与扩展名 #

确保导入路径的扩展名正确，若你的TS配置未开启allowImportingTsExtensions，导入时需加上.ts：

import db from './src/server/db/datasource.ts';

如果开启了allowImportingTsExtensions，则可以省略扩展名，但要保证Node.js能正确识别。

内容的提问来源于stack exchange，提问作者red house 87