NGINX `ngx_http_autoindex_module` 模块目录自动索引输出神器

一、模块简介

当我们用 NGINX 部署静态文件服务时，有时会遇到这样的需求：当用户访问某个目录（以 / 结尾）但该目录下 没有 index 文件（例如 index.html、index.htm 等），我们希望自动输出该目录的文件列表，让用户可以自行浏览和下载文件。

这就是 ngx_http_autoindex_module 的用武之地。它可以自动生成目录索引页，展示目录中的文件名、大小、修改时间等信息，省去了人工编写 HTML 页面维护文件列表的麻烦。

二、模块特性

• 自动生成目录文件索引；
• 支持多种输出格式（HTML、XML、JSON、JSONP）；
• 可选择精确或简化的文件大小显示；
• 可选择使用本地时间或 UTC 时间显示文件修改时间。

需要注意的是：
该模块 默认未启用，需要在编译 NGINX 时加上 --with-http_autoindex_module 参数。

三、典型配置示例

location /files/ {
    autoindex on;
}

这个配置会让 /files/ 目录下的访问自动展示目录列表。

四、核心指令详解

1. autoindex

作用：启用或关闭目录索引。

语法：

autoindex on | off;

示例：

autoindex on;

默认是 off，需要手动开启。

2. autoindex_exact_size

作用：是否在 HTML 格式下显示文件的精确大小（字节数），或者自动转为 KB、MB、GB。

语法：

autoindex_exact_size on | off;

示例：

autoindex_exact_size off;

• on：输出精确字节数（如 12345678）。
• off：输出带单位的大小（如 12 MB）。

3. autoindex_format

作用：定义目录索引的输出格式。

语法：

autoindex_format html | xml | json | jsonp;

示例：

autoindex_format json;

• html：默认值，网页格式；
• xml：适合与 ngx_http_xslt_module 配合做 XSLT 处理；
• json：机器可读的 JSON 格式；
• jsonp：适合前端跨域请求，需要指定 callback 参数。

如果用 jsonp，URL 里要带 callback，例如：

/files/?callback=myFunction

4. autoindex_localtime

作用：在 HTML 格式下，是否显示本地时间。

语法：

autoindex_localtime on | off;

示例：

autoindex_localtime on;

• on：显示服务器本地时间；
• off：显示 UTC 时间。

五、进阶配置示例

location /public/ {
    autoindex on;
    autoindex_exact_size off;
    autoindex_format json;
    autoindex_localtime on;
}

这个配置的效果：

• 开启目录索引；
• 文件大小按 KB、MB、GB 显示；
• 目录索引输出为 JSON 格式；
• 时间显示为服务器本地时间。

六、最佳实践建议

• 文件分享场景
  在文件分享、团队内部文档、日志下载等场景下，用 autoindex 可以省去开发和维护工作量。

• 前端配合 JSONP
  前端需要跨域获取文件列表时，建议用 autoindex_format jsonp，结合 callback 使用。

• 安全防护
  如果你不希望暴露某些目录，务必关闭 autoindex，或者用 deny all 拦截敏感目录。

七、总结

ngx_http_autoindex_module 是 NGINX 提供的一个小巧却非常实用的模块，用于目录索引展示。
它不仅可以提升开发效率，还可以在很多场景下为文件分享、调试、运维提供便利。

配置示例：

location /downloads/ {
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
}

快去给你的 NGINX 配上这个“自动化小助手”吧！