pip 提示 externally-managed-environment：本机与 GitHub Actions 分别处理

执行 pip install 时出现 error: externally-managed-environment，通常表示你正在向由操作系统等外部工具管理的 Python 环境安装包。先确认解释器来源，再选择项目虚拟环境或独立配置的 Python；反复加 sudo 或 --user，并不一定能改变这项限制。

CI 中也会遇到这项限制。ubuntu-latest 的 runner 镜像会变更，工作流如果依赖系统自带的 Python，可能在镜像切换后开始失败。可以显式使用 actions/setup-python 选择项目所需的解释器，不要假定系统 Python 已取消这项保护。

这条错误在保护哪一个环境

Python 打包规范定义了 EXTERNALLY-MANAGED 标记。包安装工具在虚拟环境之外遇到相应标记时，应阻止默认的环境修改，并引导用户采用合适的安装方式。这是环境管理规则，不等于这个包无法安装，也不一定是 pip 自身损坏。

先在发生错误的终端或 CI 步骤中核对解释器和 pip：

command -v python3
command -v pip3
python3 -m pip --version
python3 -c 'import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)'

python3 -m pip 明确使用这个解释器的 pip；独立的 pip3 命令可能指向另一套安装。标准 venv 中，sys.prefix 与 sys.base_prefix 不同，可以用来判断当前是否处在该虚拟环境。它不是所有独立 Python 安装方式的统一判据，仍要结合可执行文件路径判断。

如果报错文本附带发行版的安装建议，保留其中的适用条件。不要删除系统的标记文件：它是在说明谁负责维护这套 Python，删掉它不会让系统包与 pip 包突然变得兼容。

本机项目：让依赖进入项目虚拟环境

对于项目依赖，可以在项目目录创建 venv，并直接使用其中的解释器安装。下面假设项目已有 requirements.txt：

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip --version

这是 macOS／Linux 的路径写法。Windows 的解释器通常位于 .venv\Scripts\python.exe。.venv 只是示例目录名，换成 venv 并不会天然导致或修复 externally-managed 错误；真正要确认的是执行了哪一个解释器。

直接指定虚拟环境里的 Python，不需要依赖激活是否成功。你也可以激活虚拟环境，再使用 python -m pip，但 IDE、计划任务和服务启动命令也必须选中同一个环境，否则终端安装好了，应用仍可能找不到包。

如果创建环境时报缺少 venv 支持，先按发行版提示安装相应的系统组件。Debian／Ubuntu 常见的组件名包含 python3-venv，但指定 Python 小版本、第三方安装或其他发行版可能不同，不能把一个 apt 命令套到所有机器。

创建新环境会占用目录和安装依赖，不会自动迁移旧环境中的包。已有项目先保存依赖清单和当前解释器配置，完成新环境安装与验证后再切换 IDE 或服务。若新环境不合适，可以恢复原启动配置；不要在验证前删掉仍在使用的旧环境。

GitHub Actions：不要依赖 runner 恰好提供的 Python

CI 中先看失败日志里的 runner 镜像版本、Python 路径以及 pip 输出。ubuntu-latest 标签不保证系统软件长期固定，同一个工作流在镜像切换前后也可能使用不同环境。

已有仓库检出步骤之后，可以显式设置项目所需的 Python。以下是工作流的 steps 片段，项目假设使用 Python 3.12：

- uses: actions/setup-python@v7
  with:
    python-version: '3.12'
- name: Install project dependencies
  run: |
    python -c 'import sys; print(sys.executable)'
    python -m pip --version
    python -m pip install -r requirements.txt

setup-python 会配置对应 Python 并默认加入 PATH。这里写明 python-version，避免它继续使用 PATH 中碰巧存在的版本。后续用 python -m pip 将安装动作与所选解释器绑定。

片段使用 setup-python v7。自托管 runner 还要满足 Action 的运行时要求：Node 24 运行时需要 runner 2.327.1 或以上。不能只改 Action 名称而忽略旧 runner，也不要在安装步骤中重新写死 /usr/bin/python3，绕回系统解释器。

如果工作流出于项目隔离需要再创建 venv，也可以继续使用虚拟环境中的 Python。先看实际路径，再判断错误有没有消失；不要把所有 CI 安装命令机械地替换成带 --break-system-packages 的版本。

什么时候使用系统包管理器

如果需求是给系统服务补充由发行版管理的 Python 组件，优先查发行版是否提供对应软件包，让系统工具维护那套环境。若是安装一个独立的 Python 命令行工具，可以考虑专门管理隔离环境的工具，例如 pipx；它与项目依赖的用途不同。

--break-system-packages 是明确允许突破保护的选择，会改变系统管理环境的风险边界。只有已经理解环境归属和恢复方式的特殊场景才应考虑，不能把它写成一般开发项目的首选修复。sudo pip 或删标记文件也没有解决环境混用的问题。

验收时检查程序与安装环境一致

先确认安装输出不再出现 externally-managed 错误，pip 的路径属于计划中的解释器或 venv。随后用同一个解释器导入所需依赖、运行项目原有的检查或测试。

CI 还应核对下一次任务中的 Python 版本与路径；本机则重开终端、重开 IDE 或重新启动按计划切换的服务，确认它们仍使用正确环境。只看某次 pip install 返回成功，无法保证真正运行应用的 Python 能找到这些包。