使用Gulp构建项目时遭遇TypeError [ERR_UNKNOWN_FILE_EXTENSION]错误

问题场景 #

运行gulp build命令时触发以下错误：

> gulp build
[19:18:42] Requiring external module ts-node/register
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /Users/xiaoqiangjiang/source/reddwarf/frontend/codemirror-tex/packages/lang-tex/gulpfile.ts
    at new NodeError (node:internal/errors:371:5)
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:87:11)
    at defaultGetFormat (node:internal/modules/esm/get_format:102:38)
    at defaultLoad (node:internal/modules/esm/load:21:14)
    at ESMLoader.load (node:internal/modules/esm/loader:359:26)
    at ESMLoader.moduleProvider (node:internal/modules/esm/loader:280:58)
    at new ModuleJob (node:internal/modules/esm/module_job:66:26)
    at ESMLoader.#createModuleJob (node:internal/modules/esm/loader:297:17)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:261:34)
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

项目相关配置如下：

初始tsconfig.json #

{
  "extends": "./tsconfig.build.json",
  "compilerOptions": {
    "module": "commonjs",
    "rootDir": "."
  },
  "include": ["src", "tests", "tools", "playground", "scripts", "**/*.json"]
}

修改后的tsconfig.json（未解决问题） #

{
  "extends": "./tsconfig.build.json",
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Node",
    "rootDir": "."
  },
  "include": ["src", "tests", "tools", "playground", "scripts", "**/*.json"]
}

package.json #

{
  "name": "rd-lang-tex",
  "version": "0.0.2",
  "description": "TeX extension for CodeMirror 6",
  "keywords": [
    "tex",
    "codemirror",
    "codemirror6",
    "latex",
    "cm6",
    "cm",
    "language"
  ],
  "author": "mu.io <dev@mathematic.io>",
  "homepage": "https://github.com/mu-io/codemirror-tex",
  "license": "GPL-3.0-or-later",
  "main": "lib/index.js",
  "type": "module",
  "directories": {
    "lib": "lib"
  },
  "files": [
    "lib"
  ],
  "publishConfig": {
    "access": "public"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/mu-io/codemirror-tex.git"
  },
  "scripts": {
    "serve": "gulp serve",
    "build": "gulp build"
  },
  "devDependencies": {
    "@types/gulp": "^4.0.16",
    "@types/gulp-sourcemaps": "^0.0.34",
    "@types/jest": "^26.0.24",
    "@types/webpack-dev-server": "^3.11.6",
    "clean-webpack-plugin": "^3.0.0",
    "codemirror": "^6.0.1",
    "gulp": "^4.0.2",
    "gulp-sourcemaps": "^3.0.0",
    "gulp-typescript": "6.0.0-alpha.1",
    "html-webpack-plugin": "^5.5.3",
    "jest": "^26.6.3",
    "ts-jest": "^26.5.6",
    "ts-loader": "^8.4.0",
    "ts-node": "10.8.1",
    "typescript": "^4.9.5",
    "webpack": "^5.89.0",
    "webpack-cli": "^5.1.4",
    "webpack-dev-server": "^4.15.1"
  },
  "dependencies": {
    "@codemirror/autocomplete": "^0.18.8",
    "@codemirror/closebrackets": "^0.18.0",
    "@codemirror/highlight": "^0.18.4",
    "@codemirror/language": "^0.18.2",
    "@codemirror/state": "^6.3.1",
    "@lezer/lr": "^1.3.13",
    "rd-lezer-tex": "^0.0.1"
  },
  "bugs": {
    "url": "https://github.com/mu-io/codemirror-tex/issues"
  }
}

已知Node版本为v16.14.2，移除"type": "module"后问题仍存在。

解决方案 #

1. 调整Gulp命令的ts-node调用方式 #

直接用ts-node运行gulpfile，绕开gulp自动加载ts-node的逻辑。修改package.json的scripts：

"scripts": {
  "serve": "ts-node node_modules/gulp/bin/gulp.js serve",
  "build": "ts-node node_modules/gulp/bin/gulp.js build"
}

2. 为ts-node单独配置编译选项 #

在项目根目录创建tsconfig.node.json，专门适配gulpfile的Node环境：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS",
    "moduleResolution": "Node",
    "target": "ES2017",
    "esModuleInterop": true
  },
  "include": ["gulpfile.ts"]
}

再修改scripts指定使用该配置：

"scripts": {
  "serve": "ts-node --project tsconfig.node.json node_modules/gulp/bin/gulp.js serve",
  "build": "ts-node --project tsconfig.node.json node_modules/gulp/bin/gulp.js build"
}

3. 检查tsconfig.build.json的继承影响 #

如果tsconfig.build.json中compilerOptions.module设置为ES模块，会干扰主配置的模块规范。可以确认该文件的module配置，或者通过tsconfig.node.json强制覆盖为CommonJS。

4. 调整ts-node版本 #

当前使用的ts-node@10.8.1在Node 16环境下可能存在兼容性问题，尝试升级到ts-node@12.x或降级到10.7.0版本，测试是否解决文件扩展名识别问题。

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