导入GitHub私有包运行Firebase Functions模拟器报Cannot find module错误

1. 优先检查私有包的发布配置 #

• 确认私有包是否已编译为JS产物：你在node_modules里看到的api.ts是TypeScript源文件，Node.js的CommonJS加载器默认不会识别.ts后缀，私有包发布前必须完成编译，将生成的.js、.d.ts文件输出到包目录。如果暂时不想修改私有包，可以在当前项目的tsconfig.json的compilerOptions中添加"allowJs": true临时兼容。
• 确认私有包包配置是否支持子路径导入：如果需要使用@company/package/api这种子路径导入格式，需要在私有包的package.json中配置exports字段，示例如下：

  {
    "main": "./dist/index.js",
    "exports": {
      "./api": "./dist/api.js"
    }
  }
  

  未配置exports字段时，Node.js会默认在包根目录查找api.js文件，若你的编译产物存放在dist等子目录下就会触发找不到模块的错误。

2. 调整当前Functions项目的配置 #

• 在项目tsconfig.json的compilerOptions中添加明确的模块解析规则：

  {
    "compilerOptions": {
      // 原有配置保留，新增以下两行
      "moduleResolution": "node",
      "allowSyntheticDefaultImports": true
    }
  }
  

  若你的私有包仅提供ESM格式产物，可将module改为ESNext、moduleResolution改为NodeNext，同时在functions目录的package.json中添加"type": "module"开启Firebase Functions的ESM支持。

3. 排查依赖安装和环境问题 #

• 确认你是在functions子目录下执行的npm install命令，而非项目根目录，Firebase Functions的依赖会单独存放在functions目录下的node_modules中。
• 你当前全局Node.js版本为16，而Functions要求的版本为14，两个版本的模块解析逻辑存在差异，可使用nvm切换到Node.js 14版本后，删除node_modules和package-lock.json重新安装依赖再测试。

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