WebdriverIO项目中为何需将TS文件以JS文件方式导入？

我在参与一个基于WebdriverIO的测试项目时，遇到了TypeScript配置的棘手问题：TypeScript转译器能正确解析TS模块，但运行时模块解析却失败。

具体示例 #

我有一个配置模块：

// config/config.ts
export const config = {};

在测试文件中导入：

// someTest.ts
import { config } from './config/config';

TypeScript编辑器能正常识别config的类型，但运行测试套件时直接报错：

[0-2] 2023-04-18T09:07:54.651Z ERROR @wdio/runner: Error: Cannot find module '/Users/ronnyefronny/projects/wdio-demo/config/config' imported from /Users/ronnyefronny/projects/wdio-demo/test/step-definitions/VoiceflowStepDefs.ts

我的tsconfig.json配置如下：

{
  "compilerOptions": {
    "moduleResolution": "node",
    "declaration": true,
    "module": "ESNext",
    "baseUrl": "./",
    "types": [
      "node",
      "@wdio/globals/types",
      "expect-webdriverio",
      "@wdio/cucumber-framework"
    ],
    "target": "ESNext",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

其余WebdriverIO配置完全遵循官方文档，但问题依旧。

核心疑惑 #

让我不解的是，WebdriverIO官方的Cucumber样板仓库中，导入TS模块时必须加上.js后缀：

import { config } from './config/config.js';

而我做过多年前后端TS项目，从来不需要用转译后的JS文件名来导入TS模块，都是用常规写法：

import { config } from './config/config';

我想搞清楚：

1. 为什么WebdriverIO场景下必须加.js后缀？
2. 两种导入方式的本质差异是什么？

原因分析 #

1. WebdriverIO的运行机制：直接执行TS文件而非先编译 #

大部分前端/后端TS项目会先把TS编译成JS，再执行编译后的文件——此时TS编译器会自动把./config/config这类导入替换成./config/config.js，匹配编译后的文件路径。

但WebdriverIO依赖的TS处理工具（如@wdio/typescript-service）采用实时转译+直接执行的逻辑：通过ts-node或esbuild在Node.js环境中实时转译TS文件，而非预先编译成JS。这种情况下，Node.js的模块解析器会直接处理原始TS文件里的导入语句——而Node.js在ES模块模式下，要求导入必须带完整后缀名，不会自动尝试.ts或.js后缀。

2. TypeScript与Node.js模块解析规则的差异 #

• TypeScript的模块解析器（moduleResolution: node）会自动尝试补充.ts、.tsx、.d.ts等后缀，所以编辑器里能正常识别./config/config的导入。
• 但Node.js的ES模块解析器严格遵循ES规范，必须指定完整的文件后缀（比如.js、.mjs）。WebdriverIO运行时，转译后的代码里的导入语句还是./config/config，Node.js找不到对应文件（实际文件是config.ts），因此报错。

3. 官方样板加.js后缀的逻辑 #

官方样板里写./config/config.js，本质是提前适配Node.js的模块解析规则：

• TypeScript会把这个导入当成“导入JS文件”，但通过实时转译工具，它会自动映射到同名的config.ts文件完成类型检查和转译。
• 运行时，转译后的代码里的导入还是./config/config.js，此时Node.js能找到转译后的临时JS文件（或通过工具直接映射到TS源文件），从而正常解析。

两种导入方式的差异 #

解决方案 #

如果你不想每次都写.js后缀，可以尝试以下配置调整：

1. 升级到TypeScript 5.0+，在tsconfig.json中开启allowImportingTsExtensions，同时在WebdriverIO配置中启用esbuild或ts-node的对应配置，让运行时支持带.ts后缀的导入。
2. 将tsconfig.json中的module设置为CommonJS（而非ESNext），Node.js的CommonJS模块解析器会自动尝试.js、.ts等后缀，但这可能与你使用的ES模块特性冲突。

不过最稳妥的方式还是遵循WebdriverIO的官方规范，在导入时加上.js后缀，避免运行时解析错误。

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