Quasar框架SSR模式使用vue3-recaptcha2报ES Module加载错误如何解决

问题根源 #

报错的核心原因是vue3-recaptcha2是标准ESM格式的包，而Quasar SSR模式下服务端构建产物默认是CommonJS格式，CommonJS的require()语法不支持直接加载ESM包。非SSR模式下代码仅运行在客户端，走ESM导入逻辑因此可以正常运行，Node.js升级后的报错变化仅为官方错误提示优化，本质问题完全一致。

解决方案 #

按优先级推荐以下三种修复方式：

方案1：配置Quasar转译第三方依赖（通用推荐） #

Quasar的build.transpile配置可以将指定的ESM第三方包转译为兼容CommonJS的格式，适配SSR双端运行要求：

• 打开项目根目录的quasar.config.js
• 找到build配置段，添加对应配置即可：

build: {
  // 保留其他原有build配置
  transpile: ['vue3-recaptcha2']
}

修改完成后重启开发服务即可生效。

方案2：仅客户端加载该插件（业务场景最优） #

reCAPTCHA本身是纯前端交互组件，服务端不需要运行相关逻辑，可以直接限制插件仅在客户端加载，从根源避免服务端加载ESM包的问题：

1. 创建boot文件src/boot/recaptcha.js，内容如下：

import { boot } from 'quasar/wrappers'

export default boot(async ({ app }) => {
  // 仅客户端执行插件加载逻辑
  if (process.env.CLIENT) {
    const VueRecaptcha = await import('vue3-recaptcha2')
    app.use(VueRecaptcha, {
      siteKey: '你的reCAPTCHA站点密钥'
    })
  }
})

2. 打开quasar.config.js，找到boot配置段，注册该boot文件并指定仅客户端生效：

boot: [
  // 保留其他原有boot配置项
  { path: 'recaptcha', client: true }
]

方案3：临时应急修改依赖配置 #

如果上述两个方案都无法生效，可通过修改第三方包配置实现紧急修复：

• 安装patch-package工具用于持久化依赖修改
• 打开node_modules/vue3-recaptcha2/package.json，删除"type": "module"配置项
• 执行npx patch-package vue3-recaptcha2生成补丁，后续重新安装依赖会自动应用该修改
  注意：该方案属于侵入式修改第三方依赖，仅适合临时应急使用，优先选择前两个方案

内容的提问来源于stack exchange，提问作者Teng Guang Yong