Azure Web App部署NodeJS应用无法安装mysql依赖致崩溃咨询

• 依赖未正确声明：本地环境全局安装过mysql包，或安装时未写入项目package.json的生产依赖清单，Azure部署阶段默认仅会安装package.json中声明的生产依赖，本地因node_modules残留可正常运行。
• 部署构建步骤被跳过：Azure应用配置中关闭了部署时构建开关，或自定义部署脚本遗漏npm install --production逻辑，且node_modules目录被.gitignore规则拦截未随代码上传，导致线上环境无对应依赖文件。
• 运行时版本不兼容：本地Node.js大版本与Azure配置的Node.js运行时版本差异过大，mysql包安装阶段因版本兼容问题报错退出，其余依赖因版本适配正常完成安装。
• 构建缓存/权限异常：Azure端Kudu构建缓存损坏，或临时目录权限不足，导致mysql包写入失败，其余依赖因已有缓存可正常加载。
• 依赖分类错误：本地安装mysql时添加了-D参数，将其归入了开发依赖（devDependencies），Azure生产环境部署默认跳过开发依赖安装。

• 查看部署日志：进入Azure门户对应Web应用的「部署中心」，查看最近一次部署的完整日志，或登录Kudu管理地址（格式为https://<你的应用名>.scm.azurewebsites.net）检索npm安装阶段的输出，定位mysql安装失败的具体报错（缺声明/版本冲突/权限不足等都会在日志中明确体现）。
• 核对依赖配置：检查本地项目根目录的package.json文件，确认mysql条目存在于dependencies字段下，而非devDependencies或完全缺失。
• 对齐运行时版本：本地执行node -v获取当前使用的Node版本，进入Azure应用「配置-常规设置」，将Node.js版本调整为与本地大版本一致。
• 校验线上文件：通过Kudu调试控制台进入site/wwwroot目录，确认根目录存在完整的package.json文件，且node_modules目录下存在mysql文件夹。

根据排查到的根因对应处理：

1. 依赖未声明/分类错误：本地项目根目录执行以下命令，重新安装并将mysql写入生产依赖：

npm uninstall mysql
npm install mysql --save-prod

确认package.json更新后重新提交部署。
2. 构建步骤被跳过：进入Azure应用「配置-应用程序设置」，添加配置项SCM_DO_BUILD_DURING_DEPLOYMENT = true，保存后重启应用，重新触发部署即可让Azure在部署阶段自动执行依赖安装。
3. 版本不兼容：优先将Azure端Node.js版本调整为与本地一致；若无法调整运行时版本，可更换为兼容性更好的mysql2包（API与mysql包几乎完全一致，性能更优），替换引用代码即可：

const mysql = require('mysql2');

4. 缓存/权限异常：在应用设置中添加WEBSITE_NODE_DEFAULT_CACHE_ENABLED = false禁用构建缓存，或通过Kudu控制台执行npm cache clean --force、清空site/wwwroot/node_modules目录后重新触发部署。

注意：不要直接将本地生成的node_modules目录上传至Azure，本地Windows/macOS环境下安装的原生依赖二进制与Azure Linux运行环境不兼容，会引发更多运行时错误，必须让Azure在部署阶段自动安装对应环境的依赖包。

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