pip 用户配置文件中 extra-index-url 未被读取，根源在于配置节（section）误用为 [user] 且缺少等号赋值，正确应使用 [global] 或 [install] 节并严格遵循 INI 语法。
pip 用户配置文件中 `extra-index-url` 未被读取，根源在于配置节（section）误用为 `[user]` 且缺少等号赋值，正确应使用 `[global]` 或 `[install]` 节并严格遵循 ini 语法。
在 pip 24.0 及后续版本中，配置文件（如 ~/.pip/pip.conf）的解析严格遵循 INI 格式规范与作用域语义。许多用户误将自定义索引源写入 [user] 节，但该节仅用于控制用户级行为参数（如 user = true），并不影响包发现逻辑。extra-index-url 是一个安装时（install-time）生效的指令型配置项，必须置于对 pip install 命令起效的配置节中——即 [global]（全局生效）或 [install]（仅对 install 子命令生效）。
此外，配置项语法必须严格符合 key = value 格式。原始配置中：
[user] extra-index-url https://<MY_TOKEN_NAME>:<MY_TOKEN>@gitlab.com/...
存在两个关键错误：
- 节名错误：[user] 不支持 extra-index-url；
- 缺失赋值符：extra-index-url 后缺少 =，导致 pip 忽略该行（即使节名正确，语法错误也会使整行失效）。
✅ 正确配置示例（推荐使用 [global] 节，确保所有 pip 命令统一生效）：
[global] extra-index-url = https://<MY_TOKEN_NAME>:<MY_TOKEN>@gitlab.com/api/v4/projects/<MY_PROJECT>/packages/pypi/simple trusted-host = gitlab.com
⚠️ 注意事项：
- trusted-host 必须与 extra-index-url 使用的域名完全匹配（如 gitlab.com），且不可带协议或路径；
- 若同时配置多个索引源，每行一个 extra-index-url = ...，pip 按顺序查询（主索引 https://pypi.org/simple/ 始终优先，随后是各 extra-index-url）；
- 修改配置后无需重启终端，但建议运行 pip config debug 验证加载路径与键值是否正确解析；
- 敏感信息（如 token）建议改用 keyring 或环境变量（PIP_EXTRA_INDEX_URL）替代硬编码，提升安全性。
验证是否生效：
pip install --user <MY_PACKAGE> -vv 2>&1 | grep "search for versions"
成功时输出应包含：
3 location(s) to search for versions of <MY_PACKAGE>: * https://pypi.org/simple/<MY_PACKAGE>/ * https://<MY_TOKEN_NAME>:<MY_TOKEN>@gitlab.com/.../<MY_PACKAGE>/
总结：extra-index-url 生效的前提是「正确的配置节 + 标准 INI 语法 + 匹配的 trusted-host」。这不是 pip 的 bug，而是配置语义与格式的精准要求。遵循上述修正，即可稳定启用私有 PyPI 仓库集成。
