GitLab CI缓存pip依赖必须显式配置路径和key：用cache: paths: [.pip-cache/]和key: "$CI_COMMIT_REF_SLUG"，禁用venv缓存，依赖冲突需靠pip check主动检测。
缓存路径必须显式指定 .pip-cache 或 ~/.cache/pip，不能只靠默认行为
GitLab CI 的 cache 机制不会自动识别 pip 的缓存位置。即使你用了 pip install --cache-dir，如果 cache: paths: 没写对，Runner 依然每次重装依赖。常见错误是只写 pip-cache 却没创建目录，或路径拼错成 .cache/pip/ 但实际 pip 写入的是 $HOME/.cache/pip。
推荐做法是统一用项目内相对路径，避免跨用户权限问题：
-
export PIP_CACHE_DIR="$CI_PROJECT_DIR/.pip-cache"在before_script中提前设置 -
cache: paths: - .pip-cache/（末尾斜杠不能省，否则可能不生效） - 确保所有
pip install命令都带--cache-dir .pip-cache参数
key 必须绑定分支或环境，否则不同分支共享缓存会出错
如果你的 cache.key 写成固定字符串（比如 "python-deps"），main 和 feature/login 分支会共用同一份缓存。一旦某个分支升级了 requests 到 2.32，另一个分支还没适配就可能因版本冲突失败。
安全写法是按分支隔离：
立即学习“Python免费学习笔记（深入）”；
-
key: "$CI_COMMIT_REF_SLUG"—— 最常用，分支名或 tag 名做 key -
key: "$CI_PROJECT_ID-$CI_COMMIT_REF_SLUG"—— 多项目共用 Runner 时加项目 ID 防串扰 - 避免用
$CI_PIPELINE_ID，它每次都不一样，等于没缓存
虚拟环境目录 venv/ 不建议加入缓存
有人想把 venv/ 整个目录缓存来跳过 python -m venv 和 pip install，这在 GitLab CI 上不可靠。原因有三：
- Runner 可能跨机器调度，
venv里硬编码的 Python 路径会失效 - 不同 commit 的
requirements.txt有微小变更时，缓存命中但实际依赖不一致 -
venv/缓存体积大，拖慢上传下载，反而抵消加速效果
正确做法是只缓存源数据（.pip-cache/），每次重建轻量 venv，用 pip install --no-deps --force-reinstall 控制粒度。
Python 版本变化时缓存自动失效，但要注意 pyproject.toml 场景
当 PYTHON_VERSION 变更（比如从 3.9 升到 3.11），GitLab 会自然生成新 cache key，旧缓存作废——这点没问题。但如果你用 poetry 或 pip-tools 管理依赖，pyproject.toml 或 requirements.in 文件本身也应纳入 cache key 计算，否则文件改了但缓存没刷新。
可行方案：
- 用
key: "$CI_COMMIT_REF_SLUG-$CI_PROJECT_ID-$(sha256sum requirements.txt | cut -d' ' -f1)"（需在before_script中计算） - 更稳的是弃用复杂 key，直接在
script开头加pip install --upgrade pip && pip install -r requirements.txt，靠.pip-cache/加速即可
缓存不是银弹，真正容易被忽略的是：缓存只加速安装，不解决依赖冲突。如果 requirements.txt 里混着 django~=4.2 和 djangorestframework==3.14 这种隐性不兼容，缓存越快，失败越早——得靠 pip check 或 pipdeptree --warn wrong 主动扫。
