如何在GitHub Pages上动态获取目录下的文件列表？

阿华AIGC实验室

2026-5-29

实现GitHub Pages目录自动索引（无需额外部署）

要在GitHub Pages上实现类似Nginx autoindex的功能，同时不需要任何额外部署（包括CI），可以利用GitHub公共API + 前端静态页面的方式来实现，具体方案如下：

核心思路

GitHub Pages本身是纯静态托管服务，不支持动态生成目录索引，但我们可以在需要索引的文件夹中添加一个index.html，通过前端JavaScript调用GitHub的公共REST API，获取当前文件夹下的文件列表，然后输出可被JS直接解析的JSON格式结果。

具体实现步骤

在目标文件夹中创建index.html
比如你要给folder目录实现索引，就在repo/folder/下创建index.html，内容如下：

<!DOCTYPE html>
<html>
<body>
<script>
  // 配置你的仓库信息
  const repoFullName = 'myname/myrepo'; // 替换为你的仓库全名（用户名/仓库名）
  const repoPathPrefix = '/myrepo/'; // 替换为你的GitHub Pages仓库路径前缀（即仓库名）

  // 获取当前页面对应的仓库内路径
  const currentPath = window.location.pathname.replace(repoPathPrefix, '');

  // 调用GitHub API获取目录内容
  fetch(`https://api.github.com/repos/${repoFullName}/contents/${currentPath}`)
    .then(res => res.json())
    .then(data => {
      // 过滤出文件（排除子文件夹），提取文件名
      const fileList = data
        .filter(item => item.type === 'file')
        .map(item => item.name);
      // 输出JSON格式的结果，方便JavaScript解析
      document.body.textContent = JSON.stringify(fileList);
    })
    .catch(err => {
      document.body.textContent = JSON.stringify({ error: err.message });
    });
</script>
</body>
</html>

提交文件到仓库
将这个index.html提交到GitHub仓库，GitHub Pages会自动同步托管，不需要任何额外的部署操作。
测试访问
现在访问myname.github.io/myrepo/folder，页面会直接返回类似["file1","file2"]的JSON字符串，完全可以被前端JavaScript直接解析使用。

注意事项

API请求限制：GitHub公共API对匿名请求有每小时60次的限制，个人使用场景完全足够；如果是高访问量需求，这个方案可能不太适用，但符合你“无额外部署”的要求的话，这是最优解。
仓库权限：该方法仅适用于公共仓库，因为私有仓库的API访问需要授权令牌，无法通过匿名请求获取内容。
子文件夹扩展：如果需要给多个子文件夹实现索引，只需要在每个子文件夹中复制一份这个index.html即可——代码会自动获取当前页面的路径，无需额外修改。

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