GitLab CI/CD中Python依赖安装失败主因是环境不隔离、缓存未配置及venv激活失效；须用python -m venv .venv创建隔离环境，激活后执行pip install -e .验证可导入性，并配置cache: paths: ["~/.cache/pip"]提升效率。
GitLab CI/CD 能自动构建 Python 环境，但关键不在“能不能”，而在 .gitlab-ci.yml 里是否正确隔离依赖、复用缓存、避开虚拟环境路径陷阱。
为什么 pip install -r requirements.txt 在 CI 里总失败？
本地能跑不等于 CI 能跑——CI 运行在干净的 Docker 镜像里，没有全局 venv，也没有你本机的 ~/.cache/pip。常见报错如 ModuleNotFoundError: No module named 'setuptools' 或 Permission denied: '/usr/local/lib/python3.x/site-packages'，本质是没用用户级安装或没激活环境。
- 始终用
python -m venv .venv创建隔离环境，别用virtualenv（可能未预装） - 激活后必须用
source .venv/bin/activate，且后续所有pip命令需在此上下文中执行 - 加
--user是权宜之计，但会污染系统路径，CI 中应避免；正确做法是确保pip走的是.venv里的副本 - 镜像选
python:3.11-slim比python:3.11更轻量，启动快，但需手动装gcc（如果依赖 C 扩展）
如何让 pip 缓存不每次都重下？
GitLab CI 默认每次作业都是全新容器，~/.cache/pip 不保留。不配缓存的话，一个中等项目每次装依赖要 2–5 分钟。
- 在
.gitlab-ci.yml顶层加cache:块，作用域为pip目录：
cache:
key: "$CI_COMMIT_REF_SLUG"
paths:
- ~/.cache/pip- 注意：不能写成
.cache/pip（相对路径），必须用~/.cache/pip，因为 GitLab Runner 的 home 是动态挂载的 - 如果用了
python -m venv .venv，不要把.venv加进cache.paths——二进制不跨平台，且不同 Python 版本间不兼容，反而导致ImportError - 可加
pip install --upgrade pip在缓存前，避免旧 pip 解析pyproject.toml出错
before_script 和 script 里该放什么？
before_script 是环境准备阶段，不是“所有命令都扔进去”的垃圾桶。放错地方会导致命令失效或权限错误。
立即学习“Python免费学习笔记（深入）”；
-
before_script只放：创建 venv、激活、升级 pip、设环境变量（如PIP_DISABLE_PIP_VERSION_CHECK=1） -
script放实际动作：安装依赖、运行测试、打包 - 激活命令
source .venv/bin/activate必须出现在每个script步骤开头，因为 GitLab CI 每个script是独立 shell 进程，不会继承上一步的激活状态 - 若用
poetry，别在before_script里poetry install—— 它默认装到全局~/.cache/pypoetry，应改用poetry install --no-root并配合cache保存~/.cache/pypoetry
为什么测试通过了，但部署时却 import 失败？
最常被忽略的一点：CI 流水线里 pytest 成功，不代表你的包已正确安装为可导入模块。很多项目直接 python test/test_main.py，绕过了 package 安装流程，导致本地开发没问题，CI 构建的 wheel 却漏了 __init__.py 或 setup.py 配置有误。
- 在
script中显式执行pip install -e .（开发模式）或pip install .（生产模式），再跑测试，才能验证 import 路径是否真实可用 - 检查
setup.py或pyproject.toml中的packages是否包含子模块，find_packages()默认不递归包含空目录 - 如果用
src/目录结构，setuptools需配package_dir={"": "src"}，否则pip install -e .后仍找不到模块
真正卡住人的从来不是语法，而是 venv 激活的 shell 生命周期、缓存路径的绝对性、以及“本地能跑”和“CI 可重现”之间的那层薄薄的信任差。
