requirements.txt中须写git+https://或git+ssh://格式的完整仓库URL，如git+https://oauth2:@gitlab.example.com/group/project.git@main#egg=mylib，必须以.git结尾、指定有效ref、含setup.py/pyproject.toml且权限正确。
requirements.txt 里怎么写 GitLab 私有仓库地址？
直接写 git+https:// 或 git+ssh:// 格式的 URL，不能只写网页地址（比如 https://gitlab.example.com/group/project），否则 pip 会报 No such file or directory: 'setup.py' 或 404。
常见写法：
-
git+https://oauth2:<your_token>@gitlab.example.com/group/project.git@main#egg=mylib</your_token>（HTTPS + Token） -
git+ssh://git@gitlab.example.com/group/project.git@v1.2.0#subdirectory=src（SSH + 指定子目录） -
-e git+https://oauth2:<your_token>@gitlab.example.com/group/project.git@develop#egg=mylib</your_token>（可编辑模式，适合开发中频繁改包）
关键点：
- URL 必须以
.git结尾，少这个后缀是高频 404 原因 -
@main、@v1.2.0这类 ref 必须真实存在，GitLab 里查不到就失败 - 如果项目结构是
project/src/mylib/，必须加#subdirectory=src，否则 pip 找不到setup.py -
#egg=后的名称要和setup.py里name=一致，否则依赖解析可能出错
为什么 pip install -r requirements.txt 会卡在 401 Unauthorized？
不是网络不通，是认证没传过去或权限不够。pip 默认不会自动读取 ~/.netrc 或系统凭据管理器里的 GitLab 登录信息，得手动塞进 URL 里。
立即学习“Python免费学习笔记（深入）”；
排查顺序：
- 确认 token 权限：GitLab Personal Access Token 必须勾选
read_repository（仅安装）或api（若还涉及 CI 触发） - 确认 token 没过期：GitLab token 页面会显示有效期，过期后 URL 里再填也没用
- 避免明文硬编码：别把 token 直接写死在
requirements.txt里，应通过环境变量注入，例如：git+https://oauth2:${GITLAB_TOKEN}@gitlab.example.com/group/project.git，再用pip install -r requirements.txt --trusted-host gitlab.example.com - HTTPS 下不加
--trusted-host会导致 pip 忽略该源，报The repository located at ... is not a trusted or secure host
项目根目录没有 setup.py 或 pyproject.toml 怎么办？
pip 安装 Git 仓库时，**必须**在检出路径下找到 setup.py 或 pyproject.toml，否则直接报 FileNotFoundError: No setup.py or pyproject.toml，跟权限无关。
解决办法：
- 检查 GitLab 仓库是否已提交这两个文件（不是本地有，是远程分支上要有）
- 如果包代码在子目录（如
lib/），除了 URL 加#subdirectory=lib，还得确保该子目录里有setup.py - 用
pip install -v -r requirements.txt查看详细日志，它会打印出 pip 实际 cd 到哪个路径去找构建文件 - 临时验证：手动执行
git clone https://oauth2:<token>@gitlab.example.com/group/project.git && cd project && python -m build</token>，能成功说明结构没问题
GitLab 项目默认分支名是 main 还是 master？
GitLab 2023 年起新项目默认分支名是 main，但老项目或手动改过的可能是 master 或其他名字。pip 解析 @main 时如果远程不存在这个分支，就会报 Could not find a version that satisfies the requirement。
确认方式：
- 打开 GitLab 项目页面 → Settings → General → Visibility, project features, permissions → Default branch
- 或者用 API 快速查：
curl -s "https://gitlab.example.com/api/v4/projects/group%2Fproject" | jq -r .default_branch - 不确定时，URL 中先不带
@ref（即用@HEAD或直接省略），但生产环境强烈建议锁定具体 tag 或 commit hash，避免意外更新破坏兼容性
最易被忽略的一点：GitLab 的「Project URL」和「Clone with HTTPS」显示的地址看起来一样，但后者末尾一定带 .git；前者是网页地址，复制过来必失败。每次粘贴前务必多看一眼右上角那个小按钮里的内容。
