fancyindex: NGINX Fancy Index 模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

• RedHat Enterprise Linux 7、8、9 和 10
• CentOS 7、8、9
• AlmaLinux 8、9
• Rocky Linux 8、9
• Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-fancyindex

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-fancyindex

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用该模块：

load_module modules/ngx_http_fancyindex_module.so;

本文档描述了 nginx-module-fancyindex v0.6.1，于 2026 年 3 月 1 日发布。

---

Nginx Fancy Index 模块

Fancy Index 模块使得生成文件列表成为可能，类似于内置的 autoindex 模块，但增加了一些样式。这是因为该模块允许对生成内容进行一定程度的自定义：

• 自定义头部，可以是本地的或远程存储的。
• 自定义底部，可以是本地的或远程存储的。
• 添加您自己的 CSS 样式规则。
• 允许选择按名称（默认）、修改时间或大小排序；可以是升序（默认）或降序。

该模块旨在与 Nginx 配合使用，这是一个由 Igor Sysoev 编写的高性能开源 Web 服务器。

要求

CentOS, RHEL, Fedora Linux

对于使用 官方稳定版 Nginx 仓库的用户，提供了 带动态模块的额外软件包仓库，并包含 fancyindex。

安装仓库配置，然后安装模块包：

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install nginx-module-fancyindex

然后在 /etc/nginx/nginx.conf 中加载模块：

load_module "modules/ngx_http_fancyindex_module.so";

macOS

用户可以通过 MacPorts 在 macOS 上安装 Nginx；fancyindex 已包含在内：

sudo port install nginx

其他平台

在大多数其他情况下，您需要 Nginx 的源代码。任何从 0.8 系列开始的版本都应该可以工作。

为了使用 fancyindex_header_ 和 fancyindex_footer_ 指令，您还需要内置于 Nginx 的 ngx_http_addition_module。

构建

1. 解压 Nginx 源代码：

   $ gunzip -c nginx-?.?.?.tar.gz | tar -xvf -
   

2. 解压 fancy indexing 模块的源代码：

   $ gunzip -c nginx-fancyindex-?.?.?.tar.gz | tar -xvf -
   

3. 切换到包含 Nginx 源代码的目录，使用所需选项运行配置脚本，并确保添加 --add-module 标志，指向包含 fancy indexing 模块源代码的目录：

   $ cd nginx-?.?.?
   $ ./configure --add-module=../nginx-fancyindex-?.?.? \
      [--with-http_addition_module] [其他所需选项]
   

   从版本 0.4.0 开始，该模块也可以作为 动态模块 构建，使用 --add-dynamic-module=… 替代，并在配置文件中使用 load_module "modules/ngx_http_fancyindex_module.so";

4. 构建并安装软件：

   $ make
   

   然后，以 root 身份执行：

   # make install
   

5. 使用模块的配置指令配置 Nginx。

示例

您可以通过在 Nginx 配置文件中的 server 部分添加以下行来测试默认的内置样式：

location / {
  fancyindex on;              # 启用 fancy indexes。
  fancyindex_exact_size off;  # 输出人类可读的文件大小。
}

主题

以下主题展示了使用该模块可以实现的自定义级别：

• 主题 由 @TheInsomniac 提供。使用自定义头部和底部。
• 主题 由 @Naereen 提供。使用自定义头部和底部。头部包含一个搜索字段，可以使用 JavaScript 按文件名进行过滤。
• 主题 由 @fraoustin 提供。使用 Material Design 元素的响应式主题。
• 主题 由 @alehaa 提供。基于 Bootstrap 4 和 FontAwesome 的简单平面主题。

指令

fancyindex

语法
fancyindex [on | off]

默认
fancyindex off

上下文
http, server, location

描述
启用或禁用 fancy 目录索引。

fancyindex_default_sort

语法
fancyindex_default_sort [name | size | date | name_desc | size_desc | date_desc]

默认
fancyindex_default_sort name

上下文
http, server, location

描述
定义默认的排序标准。

fancyindex_case_sensitive

语法
fancyindex_case_sensitive [on | off]

默认
fancyindex_case_sensitive on

上下文
http, server, location

描述
如果启用（默认设置），按名称排序将区分大小写。如果禁用，排序时将忽略大小写。

fancyindex_directories_first

语法
fancyindex_directories_first [on | off]

默认
fancyindex_directories_first on

上下文
http, server, location

描述
如果启用（默认设置），将目录分组并在所有常规文件之前进行排序。如果禁用，目录将与文件一起排序。

fancyindex_css_href

语法
fancyindex_css_href uri

默认
fancyindex_css_href ""

上下文
http, server, location

描述
允许在生成的列表中插入 CSS 样式表的链接。提供的 uri 参数将原样插入到 <link> HTML 标签中。该链接在内置 CSS 规则之后插入，因此您可以覆盖默认样式。

fancyindex_exact_size

语法
fancyindex_exact_size [on | off]

默认
fancyindex_exact_size on

上下文
http, server, location

描述
定义在目录列表中如何表示文件大小：可以是准确的，或四舍五入到千字节、兆字节和千兆字节。

fancyindex_footer

语法
fancyindex_footer path [subrequest | local]

默认
fancyindex_footer ""

上下文
http, server, location

描述
指定应插入到目录列表底部的文件。如果设置为空字符串，将发送模块提供的默认底部。可选参数指示 path 是否应被视为使用 subrequest 加载的 URI（默认），或是否指的是 local 文件。

注意

使用此指令需要内置于 Nginx 的 ngx_http_addition_module。

警告

当插入自定义头部/底部时，将发出一个子请求，因此可以使用任何 URL 作为它们的源。尽管它可以与外部 URL 一起使用，但仅支持使用内部 URL。外部 URL 完全未经测试，使用它们将导致 Nginx 在等待子请求完成时阻塞。如果您觉得外部头部/底部对您来说是必需的，请 告诉我。

fancyindex_header

语法
fancyindex_header path [subrequest | local]

默认
fancyindex_header ""

上下文
http, server, location

描述
指定应插入到目录列表顶部的文件。如果设置为空字符串，将发送模块提供的默认头部。可选参数指示 path 是否应被视为使用 subrequest 加载的 URI（默认），或是否指的是 local 文件。

注意

使用此指令需要内置于 Nginx 的 ngx_http_addition_module。

fancyindex_show_path

语法
fancyindex_show_path [on | off]

默认
fancyindex_show_path on

上下文
http, server, location

描述
是否在头部后输出路径和关闭的 \</h1> 标签。这在您希望使用 PHP 脚本处理路径显示时非常有用。

警告

仅在提供自定义头部时，可以关闭此指令。

fancyindex_show_dotfiles

语法
fancyindex_show_dotfiles [on | off]

默认
fancyindex_show_dotfiles off

上下文
http, server, location

描述
是否列出以点开头的文件。正常惯例是隐藏这些文件。

fancyindex_ignore

语法
fancyindex_ignore string1 [string2 [... stringN]]

默认
无默认值。

上下文
http, server, location

描述
指定在生成的列表中不显示的文件名列表。如果 Nginx 是使用 PCRE 支持构建的，则字符串被解释为正则表达式。

fancyindex_hide_symlinks

语法
fancyindex_hide_symlinks [on | off]

默认
fancyindex_hide_symlinks off

上下文
http, server, location

描述
启用时，生成的列表将不包含符号链接。

fancyindex_hide_parent_dir

语法
fancyindex_hide_parent_dir [on | off]

默认
fancyindex_hide_parent_dir off

上下文
http, server, location

描述
启用时，将不显示父目录。

fancyindex_localtime

语法
fancyindex_localtime [on | off]

默认
fancyindex_localtime off

上下文
http, server, location

描述
启用以本地时间显示文件时间。默认值为“off”（GMT 时间）。

fancyindex_time_format

语法
fancyindex_time_format string

默认
fancyindex_time_format "%Y-%b-%d %H:%M"

上下文
http, server, location

描述
用于时间戳的格式字符串。格式说明符是 strftime 函数支持的子集，行为与区域无关（例如，星期几和月份名称始终为英文）。支持的格式包括：

• %a: 星期几的缩写名称。
• %A: 星期几的全名。
• %b: 月份的缩写名称。
• %B: 月份的全名。
• %d: 作为十进制数字的月份中的天数（范围 01 到 31）。
• %e: 类似于 %d，作为十进制数字的月份中的天数，但前导零被空格替代。
• %F: 等同于 %Y-%m-%d（ISO 8601 日期格式）。
• %H: 作为十进制数字的小时，使用 24 小时制（范围 00 到 23）。
• %I: 作为十进制数字的小时，使用 12 小时制（范围 01 到 12）。
• %k: 作为十进制数字的小时（24 小时制）（范围 0 到 23）；单个数字前面有空格。
• %l: 作为十进制数字的小时（12 小时制）（范围 1 到 12）；单个数字前面有空格。
• %m: 作为十进制数字的月份（范围 01 到 12）。
• %M: 作为十进制数字的分钟（范围 00 到 59）。
• %p: 根据给定的时间值为 "AM" 或 "PM"。
• %P: 类似于 %p，但为小写：“am” 或 “pm”。
• %r: 上午或下午的时间表示法。等同于 %I:%M:%S %p。
• %R: 24 小时制的时间表示法（%H:%M）。
• %S: 作为十进制数字的秒（范围 00 到 60）。
• %T: 24 小时制的时间表示法（%H:%M:%S）。
• %u: 作为十进制的星期几，范围 1 到 7，星期一为 1。
• %w: 作为十进制的星期几，范围 0 到 6，星期一为 0。
• %y: 作为没有世纪的十进制数字的年份（范围 00 到 99）。
• %Y: 作为包含世纪的十进制数字的年份。

GitHub

您可以在 nginx-module-fancyindex 的 GitHub 仓库 中找到有关此模块的其他配置提示和文档。