FastAPI应用部署至Azure Web App失败，请求错误排查帮助

一、错误排查重点方向 #

• 深挖Github Actions部署日志：不要只停留在“ZIP Deploy失败”的提示，展开日志查看每一步输出，重点关注依赖安装阶段、打包阶段的报错，比如是否有包下载超时、缺失依赖声明、文件权限问题。
• 开启Azure Web App详细日志：在Azure门户进入你的Web App，依次打开「监控」→「日志流」，同时在「配置」→「常规设置」里开启详细错误日志和应用日志记录。另外可通过Kudu控制台查看D:\home\LogFiles\Application和D:\home\LogFiles\Deployment下的日志文件，这里往往能找到门户日志没显示的细节。
• 本地模拟Azure运行环境：Azure Web App的Python运行时有固定版本（如3.10、3.11），你可以用官方Docker镜像（如mcr.microsoft.com/azure-app-service/python:3.10）在本地搭建容器，把代码复制进去安装依赖后启动，看是否能复现部署时的错误，比如版本兼容性问题。
• 检查启动命令配置：FastAPI默认不会被Azure自动识别，必须指定启动命令，两种设置方式：
  • 在Azure门户「配置」→「常规设置」的「启动命令」里填写：uvicorn main:app --host 0.0.0.0 --port $PORT（用$PORT适配Azure的环境变量，不要硬编码端口）
  • 在项目根目录添加Procfile文件，内容为：web: uvicorn main:app --host 0.0.0.0 --port $PORT
• 核对依赖文件：确认requirements.txt包含所有必要依赖（如fastapi、uvicorn、python-multipart），且版本和本地一致。本地运行正常但部署失败常因为依赖版本不兼容，建议在requirements.txt里明确指定版本号，比如fastapi==0.104.1、uvicorn==0.24.0.post1。
• 检查ZIP包内容：确认Github Actions打包的ZIP没有包含冗余文件（如venv、__pycache__、.git），这些会导致部署异常。可在.gitignore里添加这些目录，或在打包命令里排除。

二、规范部署步骤指导 #

1. 本地验证：先确保本地运行uvicorn main:app --host 0.0.0.0 --port 8000能正常启动，所有接口测试通过。
2. 配置依赖：完善requirements.txt，把所有用到的包都列进去，建议用pip freeze > requirements.txt生成（但要删除本地环境无关的包）。
3. 添加启动配置：在项目根目录创建Procfile，内容为web: uvicorn main:app --host 0.0.0.0 --port $PORT，确保Azure能识别启动命令。
4. 配置Github Actions：使用官方的azure/webapps-deploy@v2 action，示例配置如下：

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python version
        uses: actions/setup-python@v5
        with:
          python-version: '3.10' # 和Azure上配置的Python版本一致
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Deploy to Azure Web App
        uses: azure/webapps-deploy@v2
        with:
          app-name: '<你的应用名>'
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}

5. 实时监控部署：部署时打开Azure的日志流，实时查看输出，一旦出现错误立即定位。

额外注意事项 #

• 环境变量：如果代码里用到了环境变量（如API密钥、配置参数），要在Azure门户「配置」→「应用程序设置」里添加，本地的.env文件不会被部署到Azure。
• 文件路径：代码里的相对路径要改为动态获取，比如用os.path.join(os.getcwd(), 'data', 'your_file.txt')，不要硬编码本地路径，避免Azure上找不到文件。

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