pip.conf 应放系统级路径（linux/macos 的 /etc/pip.conf 或 windows 的 %programdata%\pip\pip.ini）以实现跨团队统一生效，但需注意用户目录配置会覆盖系统配置，且 ci/cd 和 docker 中应显式指定配置文件或使用环境变量。
pip.conf 文件该放在哪里才生效
pip 读取配置文件有明确的优先级顺序：当前目录 pip.conf（或 pip.ini on Windows）→ 用户目录 → 系统目录。跨团队统一配置的关键是**不能依赖用户本地文件**，必须走“系统级”或“项目级显式指定”路径，否则每个成员手动改 pip.conf 就失去统一意义。
Linux/macOS 推荐放 /etc/pip.conf（需 root 权限），Windows 推荐放 %PROGRAMDATA%\pip\pip.ini（非用户目录，所有账户可见）。注意：如果用户目录下存在 ~/.pip/pip.conf，它会覆盖系统配置——这是最常见的失效原因。
- 检查是否被覆盖：
pip config debug会列出所有已加载的配置位置和值 - CI/CD 中不建议写系统级配置，应改用
--config-file参数或环境变量 - 容器环境（如 Docker）务必在镜像构建阶段 COPY 配置到
/etc/pip.conf，而非仅挂载
配置国内源时 index-url 和 extra-index-url 的区别
只写 index-url 会完全替换官方源，导致私有包（如公司内网 PyPI）无法安装；只写 extra-index-url 则仍以官方源为主，速度慢且可能触发安全扫描误报。跨团队场景下，90% 的情况应同时设置两者，并把内部源设为 index-url，公开源作为备用：
[global] index-url = https://pypi.example.com/simple/ extra-index-url = https://pypi.tuna.tsinghua.edu.cn/simple/ trusted-host = pypi.example.com trusted-host = pypi.tuna.tsinghua.edu.cn
-
trusted-host必须显式列出所有 HTTPS 域名（即使用了证书），否则 pip 3.12+ 会拒绝连接 - 若内部源支持 API token 认证，用
keyring工具存凭据，别硬编码在 conf 里 - extra-index-url 不会用于上传（
pip upload已废弃），上传目标由index-url决定
如何让团队成员无需手动配置就能自动生效
靠文档要求大家改配置不可靠。更稳的方式是：在项目根目录放 pip.conf 并通过 PIP_CONFIG_FILE 环境变量强制加载，或用 requirements.txt 头部注释声明源：
# requirements.txt --index-url https://pypi.example.com/simple/ --trusted-host pypi.example.com requests==2.31.0 flask>=2.2.0
- 使用
pip install -r requirements.txt时，这些行内参数会覆盖全局配置 - Git 仓库中可加
.pip.conf并在 README 提示运行前执行export PIP_CONFIG_FILE=$(pwd)/.pip.conf - Python 项目脚手架（如 Cookiecutter）可预置该文件，新项目开箱即用
pip 22.2+ 的 keyring 支持与凭证泄漏风险
新版 pip 支持从系统 keyring 读取私有源密码，但默认关闭。启用后，pip.conf 中的 username 字段可保留，而密码交由 keyring 管理：
[global] index-url = https://user@pypi.example.com/simple/ keyring-provider = subprocess
问题在于：如果 keyring 后端未正确初始化（如 Linux 上没装 secretstorage，macOS 上钥匙串权限异常），pip 会静默回退到无认证请求，报错却是 401 Client Error —— 容易误判为网络问题。
- 验证 keyring 是否就绪：
python -m keyring --list-backends，至少有一个 active - 首次登录私有源时，pip 会弹出交互式密码输入，之后才存入 keyring
- Docker 构建中 keyring 不可用，此时必须用
--trusted-host+--cert指向内部 CA 证书
团队统一源配置真正的难点不在写几行配置，而在于确保「所有环境路径一致、所有 pip 版本行为一致、所有认证方式可审计」。特别是混合使用虚拟环境、conda、poetry 的团队，pip 的配置可能被完全绕过——这时候得看工具链最外层怎么调用 pip，而不是只盯一个 pip.conf。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
