Directory Lister 介绍与选型指南
Directory Lister（PHPSoftwareLab/DirectoryLister）PHP 轻量目录列表/文件索引应用介绍与选型指南：定位、架构、功能特性、与 h5ai/Apaxy/filebrowser/Tiny File Manager 的量化对比与选型建议，版本与星数均于 2026-10-30 联网实查。
Directory Lister 介绍与选型指南
目标：讲清 Directory Lister 是什么、能解决什么问题、与同类目录索引工具的差异与取舍，帮助读者在「静态文件仓库/软件分发站/内网资料库」场景下做选型决策。本文所有版本号、星数、配置事实均于 2026-10-30 联网溯源官方源实查（shields.io、Packagist、docs.directorylister.com、GitHub Releases.atom），未做本地实测。
一、环境信息
本文为认知与选型篇，信息来源与查询环境如下：
- 溯源渠道：shields.io（版本/星数徽章）、repo.packagist.org（包元数据）、docs.directorylister.com（官方文档站）、github.com/DirectoryLister/DirectoryLister（Releases.atom）
- 查询日期：2026-10-30
- 本机验证网络：可直连 shields.io 与 repo.packagist.org；github.com 页面直连超时，版本事实以 shields.io 徽章返回值为准
- 本文涉及的版本事实：Directory Lister 最新稳定版 v5.8.3（Packagist 发布时间 2026-10-30T03:25:47Z，MIT 许可，要求 PHP ≥ 8.2）
💡 说明：Directory Lister 的 GitHub 仓库为 DirectoryLister/DirectoryLister，作者 Chris Kankiewicz（Packagist 用户名 PHLAK），项目官网 https://www.directorylister.com，文档站 https://docs.directorylister.com。
二、软件概述
Directory Lister 是一个 PHP 编写的轻量级「目录列表/文件索引」应用：把它指向任意一个 web 服务器可访问的目录，它会扫描该目录并生成一个可浏览、可搜索、可下载的文件索引页，无需数据库、无需后台管理进程。
官方对其定位的一句话描述（镜像元数据 org.opencontainers.image.description，2026-10-30 实查）：
📂 Directory Lister is the easiest way to expose the contents of any web-accessible folder for browsing and sharing.
几个关键身份信息（均为 2026-10-30 实查）：
| 项目 | 值 | 来源 |
|---|---|---|
| 最新稳定版 | v5.8.3（2026-10-30 发布） | Packagist / shields.io |
| 许可证 | MIT | Packagist license 字段 |
| 语言与运行要求 | PHP ≥ 8.2（需 Zip、DOM、Fileinfo、Multibyte String 扩展） | Packagist require.php / 官方安装文档 |
| GitHub 星数 | 2.5k | shields.io stars 徽章 |
| 维护活跃度 | 最近提交 today（2026-10-30 查询） | shields.io last-commit 徽章 |
| 官方 Docker 镜像 | directorylister/directorylister（v5.0 起提供） | 官方安装文档 |
⚠️ 命名辨析：Directory Lister 与 Apache Directory（ApacheDS，Red Hat 系 389 Directory Server 同类的 LDAP 目录服务器）、Apache httpd 的 mod_autoindex（Apache 内建目录索引模块）是三个完全不同的东西。Directory Lister 是一个独立的 PHP 应用，只是运行时可以借助 Apache 或 Nginx 托管；它不提供 LDAP 目录服务，也不是 Apache 模块。
💡 技术拓展：把一个目录变成 web 可浏览页面，业界有三种实现层次——
实现层次 代表 原理 适用场景 web 服务器内建索引 Apache mod_autoindex、Nginx autoindex 服务器模块直接渲染目录列表 临时开放一个目录，零部署 索引增强脚本 Directory Lister、h5ai、Apaxy 在服务器上跑一层脚本/样式，增强内建索引 对外文件仓库，要求美观/搜索/README 全功能文件管理器 filebrowser、Tiny File Manager 独立应用，带账号体系、上传、编辑 需要多人管理文件，不只是"看" Directory Lister 属于中间层：比内建索引功能完整（搜索/哈希/README/zip），比文件管理器轻得多（只读索引、无数据库）。
三、核心架构
Directory Lister 的架构极简，可以从「一个请求的生命周期」来理解（依据官方文档站 Configuration 与源码结构描述，docs.directorylister.com，2026-10-30）：
- web 服务器层：官方 Docker 镜像内置 Apache 2.4（Debian）+ PHP（启用 deflate、rewrite 模块）；手动安装时则要求 PHP 运行环境具备 Zip、DOM、Fileinfo、Multibyte String 四个扩展。
- 应用层：入口是单个
index.php，基于 PHP-DI 依赖注入容器组织配置与请求处理。请求参数风格为查询串：?dir=<子目录>浏览、?file=<文件名>下载、?search=<关键词>搜索、?zip=<目录>打包下载、?info=<文件名>返回文件哈希 JSON。 - 配置层：环境变量（
.env文件或容器环境变量）是唯一的常规配置入口，涵盖排序、隐藏文件、README 渲染、zip 下载等约 22 个变量；少数高级项（hidden_files数组、Memcached/Redis 连接闭包、HTTP 缓存时长、自定义排序函数）只能写在app/config/app.php中。 - 缓存层：默认
CACHE_DRIVER=file，可选 memcached 或 redis（对应MEMCACHED_HOST/PORT、REDIS_HOST/PORT变量）；应用容器本身支持编译缓存（COMPILE_CONTAINER）。 - 模板与前端：服务端渲染 HTML，前端用 Alpine.js 做交互（暗色模式切换、文件信息弹层），代码高亮等资源打包在单页内。
这个架构带来的直接特性：没有数据库、没有常驻后台进程、没有账号体系——部署即静态目录 + 一个 PHP 应用，升级就是替换应用文件。
四、功能特性
以下特性清单整理自官方文档站 Introduction 与 Configuration Reference（2026-10-30 实查），逐项对应到配置入口：
- 零配置安装：不写任何配置也能直接工作（默认列出应用根目录）；Docker 形态下通过
FILES_PATH（镜像内预设为/data）指定要列出的目录。 - README 渲染：目录内的 README 文件会被解析为 Markdown 渲染在页面上，
DISPLAY_READMES控制开关，READMES_FIRST控制 README 显示在文件列表之前还是之后。 - 文件搜索：页面搜索框（快捷键
?聚焦），按 GET 参数?search=<关键词>过滤当前列表，无结果时返回 "No results found" 页面。 - 文件哈希校验：文件行上的 File Info 按钮展示 MD5/SHA1/SHA256，数据来自
?info=<文件名>返回的 JSON；MAX_HASH_SIZE（默认 1000000000 字节）限制参与哈希计算的文件大小上限，防止超大文件计算超时。 - zip 打包下载：
ZIP_DOWNLOADS开启后，每个目录可整体打包下载（?zip=<目录>），ZIP_COMPRESS控制是否对 zip 条目做 Deflate 压缩。 - 隐藏文件规则：
HIDE_DOT_FILES（点文件）、HIDE_VCS_FILES（Git/Mercurial 元数据）、HIDE_APP_FILES（应用自身文件）三个布尔开关，外加HIDDEN_FILES_LIST（默认.hidden清单文件）与app/config中的hidden_files数组，均支持 glob 模式（*、**、{yml,yaml}、(!…)断言等，见官方 File Matching Patterns 页）。 - 排序控制：
SORT_ORDER支持type（默认）/natural/name/accessed/changed/modified，REVERSE_SORT反转；更复杂的排序可写匿名函数。 - 多语言：内置 29 个语言包（
app/translations/下 29 个 yaml，含zh-CN.yaml、zh-TW.yaml），APP_LANGUAGE=zh-CN即切换中文界面。 - 主题：内置亮/暗两套主题，页面右上角可切换，偏好存在 cookie 中。
- 图标识别：按文件扩展名映射图标（
app/config/icons.php），常见格式可直观区分。 - 官方 Docker 镜像：v5.0 起官方发布
directorylister/directorylister，另有官方维护的 directory-lister-compose 仓库提供预打包的 Compose 配置。
五、快速开始（最小可用示例）
Directory Lister v5.0 起官方提供 Docker 镜像，最小可用只需要一条命令（以下形式照自官方安装文档 Docker Run 节，2026-10-30 实查；<host_path> 换成你要列出的目录，<host_port> 换成空闲端口）：
docker run --detach \
--volume /srv/files:/data \
--publish 8080:80 \
directorylister/directorylister:5
启动后浏览器访问 http://<服务器IP>:8080 即看到 /srv/files 的文件索引页。这个最小示例适合先验证功能；长期部署建议使用 Docker Compose 并固定版本号，完整步骤（含自定义端口、网络、.hidden 隐藏清单与升级方法）见本专栏部署篇。
💡 说明：手动安装路径同样简单——从官网 https://www.directorylister.com 下载压缩包，解压拷贝到 web 服务器目录即可；或使用
composer create-project phlak/directory-lister（Packagist 实查）。两种方式的配置入口都是应用根目录的.env文件。
六、适用场景与限制
6.1 适用场景
结合其「只读索引、无数据库、无账号」的形态，Directory Lister 适合：
- 软件/安装包分发站：对外提供固定版本文件的下载入口，README 渲染 + 文件哈希可承担"说明 + 校验"两个职责。
- 内网资料库/文档归档浏览：团队把已有的目录结构直接暴露为可搜索的索引页，零迁移成本。
- 构建产物/备份目录的快速浏览：配合
HIDDEN_FILES_LIST隐藏中间产物，只暴露交付物。 - 作为 Nginx/Apache autoindex 的升级替代：当内建索引的朴素列表不够用时（需要搜索、README、哈希、zip 打包）。
6.2 限制
- 无内置认证：官方文档明确"Directory Lister does not include any form of authentication out of the box"（Authentication 页，2026-10-30 实查），公开部署即全公开；需要认证时官方给出的路径是 HTTP Basic（Apache
.htpasswd/ Nginx Basic Auth）或 Authelia 反代授权。 - 只读索引，无上传/管理：不能通过页面上传、重命名、删除文件；这些需求属于 filebrowser/Tiny File Manager 一类全功能管理器的范畴。
- 无细粒度权限：没有用户/目录 ACL 概念，隐藏文件规则是"展示层过滤"而非访问控制（知道文件名仍可能直接访问被隐藏的文件，敏感目录应配合 web 服务器层限制）。
- 大目录与大文件：哈希计算受
MAX_HASH_SIZE上限约束；目录级 zip 打包是实时流式压缩，超大目录的首次打包耗时与带宽都发生在请求线程上。 - PHP 运行时依赖：手动安装需要 PHP ≥ 8.2 及 Zip/DOM/Fileinfo/Multibyte String 扩展；Docker 形态则无此顾虑。
七、同类选型对比
同赛道（目录索引/文件列表）主流开源工具横向对比。版本与星数为 shields.io 于 2026-10-30 实查值：
| 维度 | Directory Lister | h5ai | Apaxy | filebrowser | Tiny File Manager |
|---|---|---|---|---|---|
| 定位 | 目录索引（只读增强） | 目录索引（只读增强） | Apache autoindex 主题化 | 全功能文件管理器 | 单文件 PHP 文件管理器 |
| 实测版本 | v5.8.3 | v0.30.0 | 无正式 release（AdamWhitcroft/Apaxy） | v2.63.23 | v2.6 |
| GitHub 星数 | 2.5k | 6.1k | 1.9k | 36k | 6k |
| 实现语言/运行依赖 | PHP ≥ 8.2（Zip/DOM/Fileinfo/Mbstring） | PHP（需禁用部分函数配合） | 纯 HTML/CSS/JS + Apache autoindex | Go 单二进制 | PHP 单文件 |
| 数据库 | 无 | 无 | 无 | 无（可选用 SQLite 认证库） | 无 |
| 搜索 | 有（?search=） | 有（索引缓存） | 无（依赖浏览器页内查找） | 有 | 有 |
| README 渲染 | 有（Markdown） | 有（Markdown） | 无 | 部分（支持预览） | 无专门渲染 |
| 文件哈希展示 | 有（MD5/SHA1/SHA256） | 无 | 无 | 无 | 无 |
| 目录 zip 下载 | 有（可选 deflate） | 有（tar 打包） | 无 | 有 | 有 |
| 上传/编辑/删除 | 无 | 无 | 无 | 有 | 有 |
| 内置认证 | 无（靠 web 服务器/反代） | 无（同左） | 无（同左） | 有（多用户） | 有（登录会话） |
| 多语言 | 29 种（含 zh-CN/zh-TW） | 多语言 | 无 | 多语言 | 多语言 |
| 许可证 | MIT | MIT | Unlicense | Apache-2.0 | 自定义（商用需授权） |
（星数/版本来源：shields.io GitHub release 与 stars 徽章，2026-10-30 实查；Apaxy 仓库无 tag 发布，以仓库 README 与 HEAD 为准。）
解读与选型建议：
- 三者对比的关键差异在「只读索引」与「文件管理器」的分界：如果你只需要把一个目录变成漂亮的、可搜索的下载页，Directory Lister / h5ai / Apaxy 这一档就够了；一旦需要上传、多用户、在线编辑，直接跳到 filebrowser / Tiny File Manager 一档。
- Directory Lister 与 h5ai 是同档直接竞品：h5ai 星数更高（6.1k）但实测最新 release 停在 v0.30.0；Directory Lister 维护节奏明显更活跃（2026-10-30 当天仍在发布，v5.8.3），且官方提供 Docker 镜像与官方 Compose 仓库，容器化部署路径更省心。
- Apaxy 最轻（纯 Apache autoindex 换肤），但功能上没有搜索/哈希/zip，且依赖 Apache；如果宿主已是 Apache 且只想要"不丑的列表"，它是最低成本选项。
- 需要哈希校验展示（软件分发场景对下载完整性敏感）是 Directory Lister 独有的差异点，上表其余工具均不提供。
- 许可证注意：Tiny File Manager 自定义许可对商用有限制；其余四者 MIT/Apache-2.0/Unlicense 均宽松。
八、参考链接
- 官网：https://www.directorylister.com
- 官方文档站（安装/配置/文件匹配模式/认证）：https://docs.directorylister.com
- GitHub 仓库：https://github.com/DirectoryLister/DirectoryLister
- 官方 Compose 仓库：https://github.com/DirectoryLister/directory-lister-compose
- Packagist 包页：https://packagist.org/packages/phlak/directory-lister
- 官方 Docker Hub：https://hub.docker.com/r/directorylister/directorylister
- 版本与星数取证：shields.io 徽章（
img.shields.io/github/v/release/DirectoryLister/DirectoryLister、img.shields.io/github/stars/DirectoryLister/DirectoryLister），查询日期 2026-10-30