自建GitLab自定义克隆URL克隆报错：找不到指定项目

报错场景 #

执行HTTPS克隆命令时触发项目找不到的错误，命令及输出如下：

git clone https://username:token@gitlab.domain.com/custom_name/xxx.git
Cloning into 'xxx'... 
remote: The project you were looking for could not be found. 
 Please make sure you have the correct access rights and the repository exists.
fatal: repository 'https://username:token@gitlab.domain.com/custom_name/xxx.git' not found

关键信息 #

• 使用的自定义克隆URL格式：gitlab.domain.com/custom_name/*
• 已配置SSH密钥且服务器连接验证成功
• 移除自定义克隆URL设置后，克隆操作可正常执行
• GitLab环境配置：
  • 版本：16.1.2-ee
  • 修订版本：0642e8c5c91
  • 克隆方式：仅允许HTTPS
  • 全员强制开启2FA

已尝试的无效方案 #

• 排查“项目不存在或无权限查看”相关方案
• 排查“无法克隆GitLab仓库”相关方案
• 排查“GitLab克隆提示项目找不到”相关方案

解决建议 #

1. 校验自定义克隆URL的重定向规则
   自定义克隆URL本质是GitLab的路由重定向配置，需确认custom_name对应的规则是否精准映射到实际项目路径。比如实际项目路径为gitlab.domain.com/group/xxx.git，重定向规则必须准确匹配，避免路径拼接错误导致路由失效。

2. 检查访问令牌的权限与格式
   因全员开启2FA，必须使用**个人访问令牌（PAT）**而非账号密码。确认令牌已开启read_repository权限，同时检查URL中的令牌是否包含特殊字符（如/、@），若有需进行URL编码后再使用。

3. 排查自定义URL的路径冲突
   GitLab 16.x版本的自定义克隆URL可能存在路由匹配优先级问题，确认custom_name未与现有群组、项目名称重名，否则会导致路由混淆，无法正确定位目标仓库。

4. 验证重定向是否生效
   直接在浏览器访问https://gitlab.domain.com/custom_name/xxx.git，观察是否能正确跳转到目标项目的仓库页面。若跳转失败，说明重定向配置本身存在错误。

5. 查看GitLab日志定位根因
   登录GitLab服务器，查看/var/log/gitlab/gitlab-rails/production.log，搜索请求路径/custom_name/xxx.git，通过日志中的路由错误、权限校验信息，精准定位问题所在。

内容的提问来源于stack exchange，提问作者Raymond A