Azure Static Web App托管函数部署后报找不到模块错误如何解决

问题场景 #

现有一个包含5个包的monorepo项目，结构如下：

• frontend：前端静态站点包
• backend：Azure Functions 后端服务包，依赖其余三个内部库
• library 1/library 2/library 3：内部公共依赖库
  使用SWA CLI本地模拟运行时所有功能正常，完成云端部署后函数执行抛出模块找不到错误，错误日志如下：

Exception while executing function: Functions.npm-dependency-report Result: Failure
Exception: Worker was unable to load function npm-dependency-report: 'Cannot find module 'rimraf'
Require stack:
- /home/site/wwwroot/dist/npm-dependency-report/index.js
- /azure-functions-host/workers/node/dist/src/worker-bundle.js
- /azure-functions-host/workers/node/dist/src/nodejsWorker.js'
Stack: Error: Cannot find module 'rimraf'
Require stack:
- /home/site/wwwroot/dist/npm-dependency-report/index.js
- /azure-functions-host/workers/node/dist/src/worker-bundle.js
- /azure-functions-host/workers/node/dist/src/nodejsWorker.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at Object.apply (/azure-functions-host/workers/node/dist/src/worker-bundle.js:2:38624)
    at require (node:internal/modules/cjs/helpers:102:18)
    at /home/site/wwwroot/dist/npm-dependency-report/index.js:279:5348
    at /home/site/wwwroot/dist/npm-dependency-report/index.js:1:222
    at /home/site/wwwroot/dist/npm-dependency-report/index.js:279:12306
    at /home/site/wwwroot/dist/npm-dependency-report/index.js:1:222
    at Object.<anonymous> (/home/site/wwwroot/dist/npm-dependency-report/index.js:283:1294)

已确认的信息：

• rimraf 已完成安装，且在后端项目的package.json中显式声明
• 删除代码中调用rimraf的逻辑后，会抛出同类错误提示找不到node-gyp，该模块为某依赖的下游传递依赖，非项目直接依赖
• 本地模拟运行命令：

swa start --app-location ./packages/frontend --api-location ./packages/backend  --output-location ./dist

• 部署执行命令：

swa deploy --app-location ./packages/frontend --api-location ./packages/backend --output-location ./dist

根因说明 #

本地swa start和云端swa deploy的依赖解析逻辑不一致：本地运行时SWA CLI会自动识别monorepo的workspace软链、读取根目录提升的依赖，所以不会报模块缺失；但部署时SWA CLI只会上传指定的--api-location也就是./packages/backend目录下的文件，默认不会处理monorepo根目录提升的依赖、也不会自动安装workspace关联的内部库依赖，最终云端运行时的node_modules目录缺失对应模块，抛出找不到文件的错误。

排查解决步骤 #

按以下顺序逐一验证调整：

• 检查忽略文件规则
  查看./packages/backend目录下的.funcignore、.swaignore、.gitignore文件，确认没有配置排除node_modules目录的规则。如果存在node_modules/这类忽略项，部署时不会上传依赖目录，云端必然找不到所有npm包。
• 修正部署前的依赖安装逻辑
  不要依赖monorepo根目录提升的依赖，在执行部署命令前，单独进入backend目录执行生产依赖安装：

  cd ./packages/backend
  npm install --production --workspaces=false
  cd ../../
  

  该命令会强制在backend目录下安装所有package.json中声明的生产依赖（包括传递依赖），不使用根目录的workspace软链和提升依赖，保证backend目录下自带完整的node_modules。
• 调整内部库的依赖声明
  三个内部library如果有自己的生产依赖（比如用到了rimraf、node-gyp），不要把这些依赖放在devDependencies里，必须放到dependencies字段中。否则安装backend依赖时，不会自动安装内部库devDependencies下的包，就会出现传递依赖缺失的问题。
• 验证构建产物的依赖引用
  如果用esbuild、rollup、tsc等工具构建后端代码到dist目录，检查构建配置：
  • 不要把运行时需要的npm包（比如rimraf）标记为external后，又不把对应包打包进产物、也不把依赖安装到部署目录
  • 构建完成后检查dist目录下的代码引用路径，确认没有写死本地monorepo的软链相对路径（比如引用../../library1/dist/index.js这类路径，云端部署时目录结构和本地不一致会加载失败）
• 开启部署日志验证上传内容
  执行部署命令时加上--verbose参数，查看输出的文件上传列表，确认backend目录下的node_modules/rimraf、node_modules/node-gyp等缺失模块的目录确实被上传到了云端。如果列表中没有对应文件，回到前面的步骤检查安装路径和忽略规则。

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