Vuetify 2.4.2 导致 Gridsome 0.7.23 执行build构建触发ERR_REQUIRE_ESM报错

按照官方文档指引集成 Vuetify 时，执行 gridsome build 命令失败，具体流程如下：

前置操作 #

根据官方文档指引，需安装vuetify和webpack-node-externals两个依赖，并修改两个核心配置文件：

1. 入口文件 main.js 配置 #

//main.js
import Vuetify from 'vuetify'
import 'vuetify/dist/vuetify.min.css'
import DefaultLayout from '~/layouts/Default.vue'

export default function (Vue, { appOptions, head }) {
  head.link.push({
    rel: 'stylesheet',
    href: 'https://cdn.jsdelivr.net/npm/@mdi/font@latest/css/materialdesignicons.min.css',
  })
  
  head.link.push({
    rel: 'stylesheet',
    href: 'https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900',
  });
  
  const opts = {} //opts includes, vuetify themes, icons, etc.
  Vue.use(Vuetify)
  
  appOptions.vuetify = new Vuetify(opts);
  
  // Set default layout as a global component
  Vue.component('Layout', DefaultLayout)
}

2. 服务端配置文件 gridsome.server.js 配置 #

const nodeExternals = require('webpack-node-externals')

module.exports = function (api) {
  api.chainWebpack((config, { isServer }) => {
    if (isServer) {
      config.externals([
        nodeExternals({
          allowlist: [/^vuetify/]
        })
      ])
    }
  })

  api.loadSource(store => {
    // Use the Data store API here
  })
}

报错信息 #

修改配置后执行构建命令，输出如下错误：

PS E:\Dev\Projects\gridsome-vuetify-test> gridsome build
Gridsome v0.7.23

Initializing plugins...
Load sources - 0s
Create GraphQL schema - 0.03s
Create pages and templates - 0.03s
Generate temporary code - 0.04s
Bootstrap finish - 1.29s
Compile assets - 6.72s
Execute GraphQL (3 queries) - 0.01s
Could not generate HTML for "/about/":
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: E:\Dev\Projects\gridsome-vuetify-test\node_modules\@babel\runtime\helpers\esm\unsupportedIterableToArray.js
require() of ES modules is not supported.
require() of E:\Dev\Projects\gridsome-vuetify-test\node_modules\@babel\runtime\helpers\esm\unsupportedIterableToArray.js from E:\Dev\Projects\gridsome-vuetify-test\node_modules\vue-server-renderer\build.prod.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename unsupportedIterableToArray.js to end in .cjs, change the requiring 
code to use import(), or remove "type": "module" from E:\Dev\Projects\gridsome-vuetify-test\node_modules\@babel\runtime\helpers\esm\package.json.

    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1080:13)
    at Module.load (internal/modules/cjs/loader.js:928:32)
    at Function.Module._load (internal/modules/cjs/loader.js:769:14)
    at Module.require (internal/modules/cjs/loader.js:952:19)
    at require (internal/modules/cjs/helpers.js.js:88:18)
    at E:\Dev\Projects\gridsome-vuetify-test\node_modules\vue-server-renderer\build.prod.js:1:77645
    at Object.YbeR (webpack:/external "@babel/runtime/helpers/esm/unsupportedIterableToArray":1:0)
    at __webpack_require__ (webpack/bootstrap:25:0)
    at Module.O/VM (assets/js/app.46242f68.js:1744:35)
    at __webpack_require__ (webpack/bootstrap:25:0)

注：未修改 gridsome.server.js 配置前，项目本地运行正常，未找到匹配的解决方案。

报错根源是 webpack-node-externals 默认将所有 node_modules 下的依赖列为外部依赖，仅白名单内的包会被打包进服务端 bundle。当前配置仅将 vuetify 加入白名单，导致 @babel/runtime 被外部化，服务端 CommonJS 环境无法直接加载该包最新版本的 ESM 格式文件，触发 ERR_REQUIRE_ESM 错误。

操作步骤 #

方案1：调整外部依赖白名单（优先推荐） #

• 打开 gridsome.server.js 文件
• 修改 nodeExternals 的 allowlist 规则，将 @babel/runtime 加入白名单，让 webpack 将其打包进服务端 bundle，不再走外部 require 逻辑：

const nodeExternals = require('webpack-node-externals')
module.exports = function (api) {
  api.chainWebpack((config, { isServer }) => {
    if (isServer) {
      config.externals([
        nodeExternals({
          allowlist: [/^vuetify/, /^@babel\/runtime/]
        })
      ])
    }
  })
  // 原有 api.loadSource 配置保持不变
  api.loadSource(store => {})
}

• 保存后重新执行 gridsome build 测试。

方案2：锁定 @babel/runtime 兼容版本 #

如果方案1不生效，可将 @babel/runtime 降级到未启用 ESM 标记的版本：

• 执行命令锁定兼容版本：npm install @babel/runtime@7.19.0 --save-dev（yarn 用户可对应修改为 yarn add @babel/runtime@7.19.0 --dev）
• 删除 node_modules 目录和包锁文件（package-lock.json/yarn.lock）后重新安装依赖
• 再次执行构建命令测试。

方案3：适配 Vuetify 3 版本配置 #

如果使用的是 Vuetify 3.x 版本，原 Vuetify 2 的导入配置存在兼容问题，可调整入口文件 main.js 的导入逻辑：

• 将原有 Vuetify 导入代码替换为：

import Vuetify from 'vuetify/lib/framework'

• 其余配置保持不变后重新构建。

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