使用GitHub CLI部署Django应用到Azure App Service遇ZIP部署失败

问题场景 #

• 使用GitHub CLI部署Django应用至Azure App Service，此前运行正常，启用ZIP部署后出现以下错误：

Deployment Failed. deployer = GITHUB_ZIP_DEPLOY deploymentPath = ZipDeploy. Extract zip. Remote build. Error: Failed to deploy web package to App Service. Error: Deployment Failed, Package deployment using ZIP Deploy failed. Refer logs for more details.

• 添加配置项WEBSITE_RUN_FROM_PACKAGE=1后，部署无报错，但应用完全无法运行。

排查与解决步骤 #

1. 修正运行模式配置 #

移除WEBSITE_RUN_FROM_PACKAGE=1配置项——该模式会让App Service直接从ZIP包只读运行，跳过解压和远程构建流程，但Django应用需要安装依赖、收集静态文件等构建操作，因此不适用此模式。

2. 开启远程构建并配置环境 #

添加以下应用配置项，确保Azure能正确执行Django项目的构建流程：

• SCM_DO_BUILD_DURING_DEPLOYMENT=true：强制启用远程构建，自动完成依赖安装、构建命令执行
• PYTHON_VERSION=3.x：替换为你的Django兼容版本（如3.9、3.11）

3. 规范ZIP包内容 #

• 确保打包的ZIP包含Django核心文件：manage.py、项目配置目录、应用目录、requirements.txt等
• 排除虚拟环境（如venv）、缓存文件（如__pycache__）、本地配置文件，避免部署包体积过大或引发冲突

4. 自定义构建步骤 #

在项目根目录创建.deployment文件，指定构建命令确保静态文件收集和依赖安装完成：

[config]
command = pip install -r requirements.txt && python manage.py collectstatic --noinput

5. 验证启动配置 #

• 在Azure App Service的“启动命令”中设置正确的WSGI启动指令：gunicorn --bind=0.0.0.0 --workers=4 <你的项目名称>.wsgi
• 确认Django配置文件的ALLOWED_HOSTS包含App Service域名（如<app-name>.azurewebsites.net），避免主机头限制导致应用无法访问

6. 查看详细日志定位问题 #

登录Azure门户，进入对应App Service的“部署中心”→“日志”，查看具体报错细节（如依赖安装失败、静态文件收集错误等）；也可使用Azure CLI实时查看日志：

az webapp log tail --name <你的App Service名称> --resource-group <资源组名称>

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