无法编译VS Code扩展：CommonJS与ESM模块冲突问题

问题背景 #

通过以下命令创建VS Code扩展后，执行编译命令npm run compile时出现TS1479错误：

npm install -g yo generator-code
yo code

错误核心提示：CommonJS模块无法导入ECMAScript模块，具体错误来自@types/imagemin-mozjpeg、@types/imagemin-optipng、@types/imagemin-svgo、@types/imagemin-gifsicle的类型定义文件，它们尝试从ESM模块imagemin导入Plugin类型，但自身属于CommonJS模块。

环境版本：npm 10.2.4，Node.js v21.2.0

项目package.json配置：

{
  "name": "custom-scripts",
  "displayName": "custom-scripts",
  "description": "",
  "version": "0.0.1",
  "engines": {
    "vscode": "^1.84.0"
  },
  "categories": [
    "Other"
  ],
  "activationEvents": [
    "onCommand:extension.replaceAsset",
    "onCommand:extension.replaceLocaleAsset"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "custom-scripts.asset",
        "title": "Replace link with blade asset code."
      },
      {
        "command": "custom-scripts.locale_asset",
        "title": "Replace link with blade locale_asset code."
      }
    ]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./",
    "pretest": "npm run compile && npm run lint",
    "lint": "eslint src --ext ts",
    "test": "node ./out/test/runTest.js"
  },
  "devDependencies": {
    "@types/imagemin-gifsicle": "^7.0.4",
    "@types/mocha": "^10.0.3",
    "@types/node": "18.x",
    "@types/vscode": "^1.84.0",
    "@typescript-eslint/eslint-plugin": "^6.9.0",
    "@typescript-eslint/parser": "^6.9.0",
    "@vscode/test-electron": "^2.3.6",
    "eslint": "^8.52.0",
    "glob": "^10.3.10",
    "mocha": "^10.2.0",
    "typescript": "^5.2.2"
  }
}

解决方法 #

1. 移除无关依赖（优先推荐） #

你的扩展功能是实现Blade资源链接替换，与imagemin系列工具无任何关联，@types/imagemin-gifsicle属于误安装的依赖。执行以下命令卸载该依赖：

npm uninstall @types/imagemin-gifsicle

若存在其他@types/imagemin-*相关依赖，可一并卸载，彻底解决类型冲突问题。

2. 跳过第三方类型库检查 #

若需保留相关依赖，可修改tsconfig.json，添加skipLibCheck配置，让TypeScript跳过第三方类型文件的检查：

{
  "compilerOptions": {
    // 保留原有配置
    "skipLibCheck": true
  }
}

此配置仅会忽略第三方库之间的类型冲突，不影响自身代码的类型检查。

3. 调整模块解析策略 #

修改tsconfig.json的模块解析配置，优化CommonJS与ESM混合场景的处理：

{
  "compilerOptions": {
    // 保留原有配置
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

moduleResolution: "bundler"是TypeScript 5.0+新增的解析策略，更适配现代打包工具，能更智能地处理不同模块类型的导入逻辑。

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