Linux Azure App Service上Python Flask应用的模块找不到异常问题

应用结构 #

• app.py
• other_modules_used_by_app_py.py
• azure_pipeline_definition_for_build.yaml
• requirements.txt

app.py依赖的模块通过import引用了requirements.txt中声明的第三方包（如pyyaml、sqlparse）。构建阶段使用的Azure DevOps YAML片段如下：

- task: Bash@3
  displayName: 'Install Python dependencies'
  inputs:
    targetType: 'inline'
    script: |
      python3.9 -m venv antenv
      source antenv/bin/activate
      pip3 install --upgrade pip
      pip3 install --upgrade setuptools
      pip3 install --upgrade setuptools_rust
      pip3 install uamqp --upgrade --no-cache-dir
      pip3 install -r requirements.txt --upgrade --no-cache-dir

异常表现 #

1. 构建日志显示依赖安装成功，但发布后Web App报ModuleNotFoundError: No module named yaml，执行pip3 list看不到pyyaml。
2. SSH进入Web App后，虚拟环境/home/site/wwwroot/antenv/lib/python3.9/site-packages/下存在pyyaml的文件，但Python Shell中import yaml仍报错。
3. 已开启SCM_DO_BUILD_DURING_DEPLOYMENT设置为true/1，问题未解决。
4. 将pyyaml的yaml目录复制到项目根目录后，应用可正常运行，但pip3 list仍无pyyaml记录。

原因分析 #

1. 虚拟环境未被运行时加载：Azure Web App默认不会自动激活构建阶段创建的antenv虚拟环境，运行时使用的是系统全局Python，而全局环境未安装依赖。
2. 路径关联失效：构建时安装到虚拟环境的依赖，运行时Python解释器的sys.path未包含该虚拟环境的site-packages目录，导致无法找到模块。
3. SCM构建的环境隔离：即便开启了SCM_DO_BUILD_DURING_DEPLOYMENT，构建生成的虚拟环境可能未被正确关联到Web App的运行环境。

解决方案 #

1. 指定运行时使用虚拟环境的Python #

修改Web App的应用设置STARTUP_COMMAND，强制使用虚拟环境内的Python解释器启动应用：

/home/site/wwwroot/antenv/bin/python -m gunicorn app:app

（根据实际使用的WSGI服务器调整命令，确保指向虚拟环境的Python）

2. 直接安装到全局环境（临时应急） #

修改构建管道脚本，跳过虚拟环境，直接将依赖安装到系统全局Python环境：

- task: Bash@3
  displayName: 'Install Python dependencies'
  inputs:
    targetType: 'inline'
    script: |
      pip3 install --upgrade pip
      pip3 install --upgrade setuptools
      pip3 install --upgrade setuptools_rust
      pip3 install uamqp --upgrade --no-cache-dir
      pip3 install -r requirements.txt --upgrade --no-cache-dir

注意：全局环境存在版本冲突风险，仅作为临时解决办法。

3. 利用SCM的自动构建脚本 #

在项目根目录创建post_build.sh脚本，让SCM构建时自动处理虚拟环境和依赖安装：

#!/bin/bash
python3.9 -m venv antenv
source antenv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

确保requirements.txt包含所有依赖，且SCM_DO_BUILD_DURING_DEPLOYMENT保持为true。

4. 检查requirements.txt的正确性 #

确认requirements.txt中声明的是pyyaml（而非yaml，因为pip install pyyaml才会安装yaml模块），示例：

pyyaml>=6.0
sqlparse>=0.4.4

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