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 一起使用，这是一个高性能的开源 Web 服务器，由 Igor Sysoev 编写。

要求

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_ 指令，您还需要将 ngx_http_addition_module 内置于 Nginx。

构建

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 是否应被视为 URI 以使用 subrequest 加载（默认），或是否指的是 local 文件。

注意

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

警告

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

fancyindex_header

语法
fancyindex_header path [subrequest | local]

默认
fancyindex_header ""

上下文
http, server, location

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

注意

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

fancyindex_show_path

语法
fancyindex_show_path [on | off]

默认
fancyindex_show_path on

上下文
http, server, location

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

警告

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

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 仓库 中找到有关此模块的其他配置提示和文档。