FrankenPHP中文文件名乱码本质是PHP跨系统文件编码处理差异所致：Linux/macOS文件名无编码元信息，若路径由GBK等非UTF-8编码生成，而PHP在UTF-8 locale下直接操作，就会报错或显示为???；解决需统一系统locale、PHP层显式转码路径、约束前端传输编码。

FrankenPHP 读取中文文件名乱码，本质不是 FrankenPHP 特有缺陷，而是 PHP 在不同操作系统（尤其是 Linux/macOS 与 Windows）下对文件系统编码的处理逻辑差异所致。Linux 和 macOS 的文件系统本身不存储字符编码元信息，文件名以原始字节流形式存在；若 PHP 脚本在 UTF-8 环境中调用 `scandir()`、`file_exists()`、`is_dir()` 或 `fopen()` 处理含中文的路径，而该路径实际由 GBK/GB2312 编码生成（例如来自 Windows 客户端上传、旧系统导出或手动创建），就会出现“能看见但打不开”“提示 No such file or directory”或目录项显示为 `???` 的现象。 解决关键在于：**让 PHP 内部字符串编码与文件系统字节序列一致**，而非强行转换文件名本身。以下是具体可落地的修改方式：

确认并统一运行环境的 locale 编码

FrankenPHP 基于 SAPI 运行，其底层行为受系统 locale 影响。Linux 下必须确保当前用户及 FrankenPHP worker 进程使用的 locale 支持 UTF-8：

• 执行 locale 查看输出，确认 LANG、LC_CTYPE 均为类似 zh_CN.UTF-8 或 en_US.UTF-8 的值
• 若非 UTF-8，临时生效：运行 export LANG=en_US.UTF-8 LC_CTYPE=en_US.UTF-8
• 永久生效：在 /etc/default/locale（Debian/Ubuntu）或 /etc/locale.conf（CentOS/RHEL）中写入 LANG="en_US.UTF-8"，然后 locale-gen && systemctl restart frankenphp

PHP 层对路径字符串做显式编码适配

当无法控制文件来源编码（如接收 Windows 用户上传的 ZIP 解压后含 GBK 文件名），需在 PHP 中将路径字符串从源编码转为当前 locale 对应的字节序列。常用组合：

• 若确定源为 GBK（常见于 Windows）：$safePath = iconv('GBK', 'UTF-8//IGNORE', $rawPath);
• 若不确定，先探测再转：$encoding = mb_detect_encoding($rawPath, ['UTF-8', 'GBK', 'BIG5'], true) ?: 'UTF-8'; $safePath = mb_convert_encoding($rawPath, 'UTF-8', $encoding);
• 注意：不要对路径直接用 utf8_encode()/utf8_decode()——它们仅适配 ISO-8859-1，对 GBK 无效

避免 fopen/scandir 直接传入未处理的中文路径

FrankenPHP 默认使用标准 PHP 文件函数，这些函数不做编码转换。安全做法是：所有涉及文件名的操作前，先标准化路径编码：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• 读取目录列表时：$files = array_map(fn($f) => iconv('GBK', 'UTF-8//IGNORE', $f), scandir($dir));
• 判断是否存在：if (file_exists(iconv('GBK', 'UTF-8//IGNORE', $path))) { ... }
• 打开文件前：$fp = fopen(iconv('GBK', 'UTF-8//IGNORE', $filePath), 'r');

前端与传输层同步约束（预防性设置）

乱码常始于源头。建议配合以下措施减少问题发生：

立即学习“PHP免费学习笔记（深入）”；

• Web 表单提交中文文件名时，HTML <form accept-charset="UTF-8"> 并确保 JS 上传时 filename 字段已 UTF-8 编码
• API 接收文件名参数时，用 mb_convert_encoding($_GET['name'] ?? '', 'UTF-8', 'auto') 预处理
• FrankenPHP 的 frankenphp.yaml 中不强制改编码，但可配置 env: 注入 LANG: en_US.UTF-8 确保子进程继承

不复杂但容易忽略。核心就三点：系统 locale 设对、PHP 路径字符串转对、源头输入控对。