如何通过GitHub API仅按文件名搜索Git仓库文件并获取路径

可能的原因及对应解决办法 #

1. 仓库权限与认证缺失
   若目标仓库是私有仓库，未携带认证信息的API请求无法访问仓库内容，直接返回空结果。解决方式：

   • 生成带有repo权限的GitHub个人访问令牌（PAT）
   • 在请求头中添加认证信息，示例curl命令：

     curl -H "Authorization: token YOUR_PAT_TOKEN" "https://api.github.com/search/code?q=filename:example.txt+repo:test/test-repo"
     

2. 仓库名/文件名的拼写或大小写错误
   GitHub仓库的所有者名、仓库名是大小写敏感的，文件名搜索虽默认不区分大小写，但拼写偏差会导致无结果：

   • 核对repo:test/test-repo中的所有者名、仓库名是否与实际完全一致（比如是否是Test/Test-Repo而非全小写）
   • 尝试用引号包裹文件名强制精确匹配，修改后的查询参数为：

     filename:"example.txt"+repo:test/test-repo
     

     转成URL后为：https://api.github.com/search/code?q=filename%3A%22example.txt%22+repo%3Atest%2Ftest-repo

3. 文件被.gitignore规则排除
   GitHub Code Search会自动忽略仓库中被.gitignore、.gitattributes标记为忽略的文件，若你的example.txt在忽略规则内，搜索会返回空结果。需检查仓库的.gitignore文件，确认目标文件未被标记为忽略。

4. API速率限制触发
   未认证请求每小时仅允许10次搜索，认证后提升至30次。若超出配额，API会返回403状态码，临时限制期间也可能出现无结果情况。可通过请求头X-RateLimit-Remaining查看剩余配额。

快速验证步骤 #

先在GitHub网页端搜索框输入filename:example.txt repo:test/test-repo，若网页端能搜到目标文件，说明API调用问题出在认证或参数转义上；若网页端也搜不到，需确认文件是否存在于仓库默认分支（API默认搜索默认分支，如main/master）。

内容的提问来源于stack exchange，提问作者Shivam Singh