如何共享自定义PyPI索引配置？如何在Python包源码中配置以通过标准构建/安装链解析私有仓库依赖？

阿华AIGC实验室

2026-4-8

嘿，这个问题我太有共鸣了！我在公司内部项目里天天跟私有PyPI索引打交道，之前也踩过requirements.txt和标准打包流程不兼容的坑。确实，Python打包生态出于安全考虑，不允许包硬编码私有索引（防止恶意包偷偷加恶意源），但咱们在内部团队/私有仓库场景下，确实需要一种不用手动改全局配置、能跟着源码走的方案。下面给你几个经过实践验证的靠谱思路：

方案1：仓库内的pip配置文件 + 环境变量注入token

这是最通用的方案，兼容pip、uv、hatch几乎所有主流工具。

你可以在仓库根目录创建一个pip.conf（Linux/macOS）或pip.ini（Windows），把私有索引配置写进去，用环境变量占位token：

[global]
# 每个私有索引单独加一行extra-index-url
extra-index-url = https://__token__:${GITLAB_TOKEN}@gitlab.mycompany.com/api/v4/projects/100/packages/pypi/simple
extra-index-url = https://__token__:${GITLAB_TOKEN}@gitlab.mycompany.com/api/v4/projects/101/packages/pypi/simple
# 记得保留公共PyPI，避免默认索引被覆盖
index-url = https://pypi.org/simple

然后告诉团队成员/CI，安装前只要设置两个环境变量就行：

# Linux/macOS 终端
export GITLAB_TOKEN=你的私有仓库令牌
export PIP_CONFIG_FILE=./pip.conf
pip install .

# Windows PowerShell
$env:GITLAB_TOKEN="你的私有仓库令牌"
$env:PIP_CONFIG_FILE="./pip.ini"
pip install .

uv和hatch都会自动读取pip的配置，所以同样适用这个方案。好处是配置跟着仓库走，不用每个人手动改全局的~/.config/pip/pip.conf，token用环境变量注入，完全符合安全要求（不会把敏感信息提交到Git）。

方案2：用`pyproject.toml`配合现代打包工具的内置配置

如果你用uv或者hatch这类现代工具，直接在pyproject.toml里写配置更优雅，不用额外的pip配置文件。

针对uv的配置

uv支持在pyproject.toml的tool.uv.index里直接定义私有索引：

[project]
name = "你的包名"
version = "0.1.0"
dependencies = [
  "my-dependency-one==3.4.2",
  "my-dependency-two==1.0.0"
]

[tool.uv.index]
# 公共PyPI默认会加，这里只需要加私有索引
extra-index-url = [
  "https://__token__:${GITLAB_TOKEN}@gitlab.mycompany.com/api/v4/projects/100/packages/pypi/simple",
  "https://__token__:${GITLAB_TOKEN}@gitlab.mycompany.com/api/v4/projects/101/packages/pypi/simple"
]

安装的时候只要设置好token，直接用uv安装就行：

export GITLAB_TOKEN=你的令牌
uv install .

针对hatch的配置

hatch可以给项目环境绑定专属索引，在pyproject.toml里这么写：

[project]
name = "你的包名"
version = "0.1.0"

[tool.hatch.envs.default]
dependencies = [
  "my-dependency-one==3.4.2",
  "my-dependency-two==1.0.0"
]
# 按顺序添加索引，最后加pypi确保公共包能正常拉取
indexes = [
  "https://__token__:${GITLAB_TOKEN}@gitlab.mycompany.com/api/v4/projects/100/packages/pypi/simple",
  "https://__token__:${GITLAB_TOKEN}@gitlab.mycompany.com/api/v4/projects/101/packages/pypi/simple",
  "pypi"
]

安装时用hatch的环境命令：

export GITLAB_TOKEN=你的令牌
hatch env create
hatch run pip install .

方案3：PEP 685 绑定单个依赖的专属索引

如果你的私有依赖分散在不同的索引（比如依赖1在项目100，依赖2在项目101），可以用PEP 685的语法，直接在依赖里指定它的来源索引，这样不会影响其他依赖的拉取：

[project]
name = "你的包名"
version = "0.1.0"
dependencies = [
  # 格式：依赖名@ 索引的依赖路径
  "my-dependency-one==3.4.2 @ https://gitlab.mycompany.com/api/v4/projects/100/packages/pypi/simple/my-dependency-one/",
  "my-dependency-two==1.0.0 @ https://gitlab.mycompany.com/api/v4/projects/101/packages/pypi/simple/my-dependency-two/"
]

这种方式需要注意，索引URL里的认证还是得靠环境变量，你可以用shell命令先替换配置里的token占位符再安装：

sed -i "s/__token__:.*@/__token__:$GITLAB_TOKEN@/g" pyproject.toml
pip install .

这个方案的好处是每个依赖绑定自己的索引，不会出现“所有依赖都去私有索引找”的问题，适合依赖分散的场景。

关键安全提醒

永远不要把令牌硬编码在仓库文件里！所有令牌必须通过环境变量注入，这是底线
仓库里的配置文件（比如pip.conf、pyproject.toml）要提交到Git，因为这是团队共享的配置，令牌是动态注入的，不会泄露
所有方案都需要用户主动启用仓库里的配置（比如设置PIP_CONFIG_FILE、用hatch环境），符合Python打包生态的安全规范——避免包偷偷添加恶意索引