Next.js React应用部署至Azure App Service无法运行问题求助

你只上传.next文件夹是最核心的错误——Next.js生产运行并非只依赖构建产物目录，缺了配套的配置、依赖声明文件根本跑不起来，网上很多旧教程因为平台迭代已经失效，按下面步骤配置即可正常运行：

1. 上传文件清单（禁止只传.next目录） #

部署时需要上传以下内容，不要传本地的node_modules目录（平台会自动安装匹配Linux环境的生产依赖，本地上传的二进制依赖会出现架构兼容问题）：

• 项目根目录的package.json、对应包管理器的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml）
• 完整的.next构建产物目录
• 项目根目录的public静态资源目录（漏传会导致图片、公共js/css全部404）
• Next配置文件：next.config.js/next.config.mjs
• 自定义服务端入口文件（如server.js，无自定义服务端可忽略）
  如果启用了Next 12+的standalone独立输出模式，需要额外把.next/static目录、根目录public目录复制到.next/standalone目录下的对应位置，再上传整个standalone目录

2. Azure 平台侧必填应用配置 #

进入App Service实例的「配置」-「应用程序设置」，添加以下键值对：

• WEBSITE_NODE_DEFAULT_VERSION：值设为16-lts，锁死Node 16运行版本，避免平台自动切换到不兼容的Node版本
• NODE_ENV：值设为production
• 所有项目中用到的NEXT_PUBLIC_*开头的前端环境变量，全部需要在这里配置，本地.env文件的变量不会自动同步到Azure环境
• PORT：值设为8080，Azure Linux App Service默认通过8080端口做应用存活探测，Next默认监听的3000端口会被平台拦截导致启动失败
• SCM_DO_BUILD_DURING_DEPLOYMENT：值设为true，让平台在部署时自动执行依赖安装，避免缺包报错

3. 正确的启动命令配置 #

进入「配置」-「常规设置」，找到「启动命令」输入框，按你的部署模式填写对应命令，不要用旧教程里的裸next start：

• 未启用standalone模式：先确保package.json里的start脚本配置为"start": "next start -p 8080"，启动命令栏填npm run start
• 启用standalone模式（推荐，包体更小启动更快）：启动命令栏填node .next/standalone/server.js
  避坑：不要在启动命令里加pm2等第三方进程守护工具，Azure平台自带进程管理，额外加进程守护会导致启动超时判定失败

4. 剩余排查点 #

• 如果上传文件后应用无响应，手动重启一次App Service实例，压缩包/FTP上传的文件不会触发平台自动重启
• 启动失败时直接看「日志流」的实时输出，90%的问题都能直接定位：
  • 报模块找不到：检查是否漏传package.json，或生产依赖未正确安装
  • 报权限错误：在启动命令前拼接chmod +x -R .next && ，给构建产物加执行权限即可
  • 报静态资源404：检查public目录、.next/static目录是否上传到正确位置

内容的提问来源于stack exchange，提问作者Tom el Safadi