Azure Linux Web App部署Next.js静态站点遇问题求助

问题背景 #

已通过Terraform配置Linux P1V3应用服务计划与Node.js 20应用服务，基于pnpm+Turbo Repo的NextJS仓库，流水线执行依赖安装、pnpm build后将apps/*/out/打包为ZIP，通过AzureRmWebAppDeployment@5部署后仍显示默认页面。修改NextJS基础路径后本地az webapp deploy成功，但流水线部署仍未生效，目标区域暂不支持静态站点服务，曾考虑切换至函数应用。

关键排查点 #

1. 流水线打包产物一致性校验 #

• 对比本地成功部署的ZIP与流水线生成的ZIP结构：确认ZIP根目录是否直接包含index.html、_next等静态文件，而非嵌套apps/xxx/out/层级。Azure应用服务要求静态入口文件位于部署包根目录或指定虚拟路径下
• 在流水线中添加ZIP内容检查步骤，例如执行unzip -l <your-zip-file>.zip并输出日志，验证所有静态文件是否完整包含

2. AzureRmWebAppDeployment@5任务参数核查 #

• 确认package参数指向正确的ZIP文件路径，避免路径错误导致部署空包或错误产物
• 检查clean参数是否设为true：强制清理应用服务中旧的默认页面文件（如hostingstart.html），防止旧文件优先级高于静态站点入口
• 若静态文件未在ZIP根目录，需配置virtualApplication参数映射到对应路径，确保应用服务能正确寻址静态资源

3. 流水线环境与本地环境一致性 #

• 验证流水线使用的Node.js版本（需严格匹配本地的20.x版本）、pnpm版本、Turbo Repo版本，避免版本差异导致构建产物异常
• 核对流水线中pnpm build的执行参数：本地是否使用了--filter等指定子应用的参数，流水线是否遗漏该配置，导致未构建目标子应用的静态产物

4. 应用服务部署后状态验证 #

• 在流水线中添加部署后校验步骤：执行az webapp deployment show --name <app-name> --resource-group <rg-name>确认部署状态，或调用curl访问站点检查返回内容
• 开启应用服务详细日志：在Azure门户的应用服务>日志>应用服务日志中启用文件系统日志，排查部署过程中是否存在文件覆盖失败、权限错误等异常
• 检查应用服务默认文档配置：在应用服务>配置>常规设置中，确保index.html排在默认文档列表的最前列，优先于hostingstart.html

5. 函数应用备选方案注意事项 #

• 若切换至函数应用，需在host.json中配置httpRoutes映射静态文件路径，或通过Blob存储挂载静态内容目录
• 确保函数应用的部署包结构符合Azure Functions要求，静态产物需放置在指定目录（如wwwroot）

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