Next.js项目中Firebase与@grpc/grpc-js不兼容报错如何解决

错误原因 #

该报错是Next.js 12的严格ES模块校验与@grpc/grpc-js的CommonJS规范不兼容导致：@grpc/grpc-js为CommonJS类型模块，不支持命名导入，而Firebase 9.6.0内部对其使用了命名导入写法，触发了Next.js的校验规则。

可行修复方案 #

方案1：配置Next.js兼容规则（无侵入，优先选择） #

在项目根目录的next.config.js中添加如下配置，宽松处理CommonJS模块的命名导入兼容：

module.exports = {
  experimental: {
    // 开启宽松ES模块外部依赖校验，自动兼容CommonJS的命名导入
    esmExternals: "loose"
  },
  // Next.js 12.1及以上版本可额外添加转译配置，确保兼容性
  transpilePackages: ['@grpc/grpc-js', 'firebase']
}

配置完成后重启项目即可生效，无需修改依赖或业务代码。

方案2：调整依赖到兼容版本 #

经过验证，以下依赖组合不存在该兼容性问题，可根据项目情况选择：

• 单独降级Firebase版本到9.5.0，执行命令：
  npm install firebase@9.5.0
• 同步升级依赖：将Next.js升级到12.1.6及以上版本，同时将Firebase升级到9.x分支的最终稳定版9.23.0，升级完成后即可解决兼容性问题。

方案3：修正导入写法 #

如果你的业务代码中直接用到了@grpc/grpc-js，将所有命名导入改为默认导入写法即可：

// 错误写法
// import { credentials, loadPackageDefinition, Metadata } from '@grpc/grpc-js'

// 正确写法
import grpc from '@grpc/grpc-js'
const { credentials, loadPackageDefinition, Metadata } = grpc

额外注意事项 #

如果你的项目仅需在浏览器端使用Firebase，不要在客户端代码中引入Firebase服务端/Admin相关模块，该类模块才会依赖@grpc/grpc-js，仅引入客户端SDK不会触发该错误。

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