Eleventy与Gulp模块兼容问题求助：ES6语法使用困境

问题背景 #

项目基于Eleventy v1.0.2、Gulp v4.0.2和Node v16.17.0开发，Gulp任务需要依赖仅支持ES模块（import语法）的第三方包，但模块系统冲突导致以下问题：

• 根目录package.json添加"type": "module"后，Eleventy加载配置文件时触发报错：

require() of ES Module /Users/user/blahblah/eleventy.js from
/Users/user/blahblah/node_modules/@11ty/eleventy/src/TemplateConfig.js
not supported.
[11ty] .eleventy.js is treated as an ES module file as it is a .js file
whose nearest parent package.json contains "type": "module" which
declares all .js files in that package scope as ES modules.

• 官方给出的三种方案均失效：
  • 重命名.eleventy.js为.eleventy.cjs，Eleventy无法识别该配置文件
  • 改回"type": "commonjs"，Gulp无法使用import加载ES模块依赖
  • 使用动态import()，未解决核心冲突
• 其他尝试的无效操作：
  • 重命名gulpfile.js为gulpfile.mjs，Gulp不支持该扩展名
  • 降级第三方包到支持require的旧版本（部分已过时3年），不符合技术迭代需求
  • Babel转译后import被转为require，仍无法适配仅支持ES模块的依赖

可行解决方案 #

1. 子目录隔离模块类型（推荐） #

通过目录拆分实现Eleventy和Gulp的模块系统隔离：

• 根目录package.json保留"type": "commonjs"，确保Eleventy正常加载.eleventy.js
• 创建gulp/子目录，在该目录下新建package.json，添加"type": "module"
• 将原gulpfile.js内容迁移到gulp/gulpfile.mjs，并修改根目录package.json的Gulp命令：

  "scripts": {
    "gulp": "gulp --gulpfile gulp/gulpfile.mjs"
  }
  

  此方案让Gulp加载子目录下的ES模块配置，Eleventy在根目录使用CommonJS，完全规避冲突。

2. 升级工具版本适配ES模块 #

• 升级Eleventy到v2.x版本：该版本全面支持ES模块配置文件，.eleventy.cjs或.eleventy.js（配合"type": "module"）均可正常识别，解决旧版本的兼容性bug
• 升级Gulp到支持ES模块的版本：配合Node v16.17.0，可尝试Gulp v4.0.2+的--esm命令行参数（部分环境有效），或直接使用gulpfile.mjs（新版本Gulp已支持）

3. 动态导入的正确用法（仅作尝试） #

若坚持根目录使用"type": "module"，可修改.eleventy.js为异步导出函数，通过动态导入处理依赖：

// .eleventy.js
export default async function(eleventyConfig) {
  // 动态导入ES模块依赖
  const esOnlyModule = await import('es-only-package');
  // 执行Eleventy配置逻辑
  eleventyConfig.addPlugin(esOnlyModule.default);
}

注意：Eleventy v1.0.2对异步配置的支持存在局限，此方案成功率较低，优先推荐前两种方案。

工具模块支持局限性说明 #

Eleventy v1.0.2的ES模块支持存在明显缺陷，官方文档中.eleventy.cjs的方案在部分环境下无法被正确识别，属于版本bug。而Gulp v4.0.2对ES模块的支持也不完善，不直接默认识别gulpfile.mjs，需要额外配置。

若追求长期的ES模块适配，升级到Eleventy v2.x + Gulp v4.x（配合Node v18+）是更彻底的解决方案，新版本工具对ES模块的支持更成熟，能避免此类冲突。

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