Directory Lister 常见问题:PHP 兼容、目录权限与语言切换

Directory Lister 是一个用 PHP 编写的单文件式目录列表程序，把服务器上的某个目录暴露成可浏览的网页列表。使用中最常卡住的地方集中在四类：PHP 版本与扩展不满足要求、目录权限配置错误导致列表为空或报错、多语言界面没有按预期切换、以及依赖更新后出现兼容问题。下面按“现象—原因—处理”的方式逐项说明。

PHP 版本与依赖兼容性

Directory Lister 依赖 PHP 运行，并通过 Composer 管理第三方依赖。官方更新记录中多次出现 “Dependency updates”，说明依赖会随版本推进而变化，这也意味着旧环境升级后可能突然不兼容。

判断和处理的顺序：

1. 先确认当前 PHP 版本。在服务器上执行 php -v，或在网站目录放一个临时 phpinfo() 页面查看。
2. 对照你所用 Directory Lister 版本的说明，确认 PHP 最低版本要求。版本越新，通常要求的 PHP 版本越高。
3. 如果升级 Directory Lister 后出现白屏、500 错误或函数未定义报错，优先怀疑 PHP 版本过低或缺少扩展（常见的是文件信息、多字节字符串相关扩展）。
4. 依赖更新后报错，可先删除 vendor 目录并重新执行 composer install，让依赖按锁文件重新拉取，而不是沿用旧的缓存。

常见卡点：把程序文件直接覆盖升级，却没有同步更新依赖，导致新旧代码混用。升级时应当同时更新程序文件和依赖。

目录权限设置

目录列表读的是文件系统，权限不对会直接表现为“页面能打开但列表为空”“某些子目录点不进去”或“500 错误”。

排查要点：

• 读取权限：Web 服务器运行用户（如 www-data、nginx、apache）需要对被列出的目录及其子目录有读取和执行权限。目录缺执行权限时，即使能读到目录名也进不去。
• 不要盲目给 777：把权限开到最大能临时验证问题是否出在权限上，但不适合作为长期方案。定位到具体是哪个用户缺权限后，再针对性调整属主或属组。
• 父目录链路：只给目标目录权限不够，从网站根目录到目标目录的整条路径都需要可进入，否则仍然访问不到。
• 符号链接：如果列表里包含指向其他位置的软链接，要确认链接目标同样对 Web 用户可读。

验证方法：用与 Web 服务器相同的用户身份在命令行尝试 ls 目标目录，能列出内容说明权限基本正确；命令行正常而网页异常，则问题更可能在程序配置而非权限。

多语言翻译的启用与切换

Directory Lister 内置多语言支持，更新记录中提到新增阿塞拜疆语（az）翻译，说明语言包会持续增加。语言没有生效通常不是翻译缺失，而是配置或缓存问题。

处理思路：

1. 确认你使用的版本已经包含目标语言。较新的语言（例如上述阿塞拜疆语）只在较新版本中加入，旧版本里不存在对应文件。
2. 检查语言配置项是否指向了正确的语言代码。语言代码一般是两位小写字母形式，写错会回退到默认语言。
3. 如果界面语言和预期不一致，先清理浏览器缓存再刷新，排除浏览器端缓存了旧页面。
4. 想新增或修改翻译，可以在语言文件基础上调整，而不是直接改模板里的硬编码文字，否则升级时会被覆盖。

常见卡点：升级程序后语言文件被覆盖，自定义翻译丢失。修改翻译前先备份，或把自定义内容放在不会被升级覆盖的位置。

依赖更新后的兼容问题

依赖更新是 Directory Lister 更新日志里的高频项，它带来安全修复和新特性，也可能引入行为变化。

遇到更新后异常，可以按这个顺序缩小范围：

• 记录更新前后的版本号，确认问题确实出现在某次更新之后。
• 查看更新日志中该版本的具体改动，判断是否涉及你正在使用的功能。
• 回退到上一个可用版本验证问题是否消失，以此确认是更新引入还是环境本身的问题。
• 重新安装依赖后再测，排除依赖文件不完整的情况。

如果问题只在特定 PHP 版本上出现，通常是依赖对 PHP 版本有区间要求，此时要么升级 PHP，要么停留在匹配的 Directory Lister 版本。

快速对照表

多数问题都能通过“先确认版本与依赖，再确认权限，最后确认配置”这个顺序定位。真正需要改代码的情况很少，先排除环境和配置，往往就能解决。