升级firebase-functions至4.3.1后出现Cannot find module 'firebase-admin/auth'错误

问题背景 #

环境：firebase-tools@11.29.1，Linux Ubuntu 22.04；将停滞维护1年的项目中firebase-functions从^{3.19.0升级到}4.3.1后，部署时触发Error: Cannot find module 'firebase-admin/auth'，即使简化index.js为仅引入firebase-functions的最简代码，错误仍存在。

核心原因 #

firebase-functions 4.x版本对firebase-admin有最低版本要求，旧项目中遗留的低版本firebase-admin（通常低于v11.5.0）不支持firebase-admin/auth这种模块化导入路径，而firebase-functions 4.x内部依赖了该路径的导入逻辑，导致部署时依赖解析失败。

解决方案 #

1. 升级firebase-admin到兼容版本 #

执行命令升级firebase-admin到满足要求的版本：

npm install firebase-admin@^11.5.0 --save

或直接升级到最新稳定版：

npm install firebase-admin@latest --save

2. 校验package.json依赖兼容性 #

确保package.json中firebase-admin和firebase-functions版本匹配，示例配置如下：

"dependencies": {
  "firebase-admin": "^11.11.1",
  "firebase-functions": "^4.3.1"
}

3. 清理本地依赖缓存并重新安装 #

删除旧的依赖文件避免缓存冲突：

rm -rf node_modules package-lock.json
npm install

4. 适配firebase-tools版本（可选） #

firebase-functions 4.x建议搭配firebase-tools@12.x及以上版本使用，若上述步骤无效，可升级firebase-tools：

npm install -g firebase-tools@latest

5. 排查隐式依赖引用 #

检查项目中所有代码文件（包括配置文件、子模块），确认是否存在require('firebase-admin/auth')或import ... from 'firebase-admin/auth'的写法。若admin版本暂无法升级，需将这类代码改为旧版兼容写法：

// 旧版写法（适配admin < v11）
const admin = require('firebase-admin');
const auth = admin.auth();

验证 #

完成上述操作后，重新执行部署命令：

firebase deploy --only functions

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