PHP在Linux环境下无法引入带变音重音目录内的PDF文件（Windows正常）

跨环境加载异常由三个核心问题共同触发，和Linux/Windows的系统层处理逻辑差异直接相关：

• 递归查找逻辑存在硬伤：原代码中子目录递归调用getFileInContents时未接住返回值，哪怕子目录内匹配到目标文件，结果也会被直接丢弃，最终函数只会遍历当前层级文件后返回null
• 编码适配不匹配：Windows系统下PHP会自动适配本地文件系统编码做隐式转换，Linux系统默认文件系统编码为UTF-8，当PHP内部字符集、GET请求传入的参数字节流、磁盘存储的目录名字节流三者不一致时，带变音重音的特殊字符（ñ、ó、ção等）哪怕视觉上完全一致，字节层面也无法匹配，导致路径识别失败
• 文件加载方式错误：PDF属于二进制文件，使用include_once加载时PHP会尝试将文件内容解析为代码执行，大概率出现语法报错或输出乱码

• 全链路统一编码为UTF-8：脚本入口声明PHP内部字符集为UTF-8，对扫描到的文件名、检索参数统一做Unicode标准化，消除同一字符的不同字节表示差异
• 修正递归查找逻辑：接住递归调用的返回值，匹配到目标后直接向上传递结果
• 替换二进制文件加载逻辑：直接读取文件流输出，避免PHP解析文件内容
• 规范响应头设置，避免浏览器错误解析输出内容

// 统一PHP内部字符集为UTF-8，匹配Linux下的UTF-8文件系统
mb_internal_encoding('UTF-8');

function getFileInContents($dir, $filename)
{
    // 标准化检索目标，消除Unicode字符的变体字节差异
    $normalizedTarget = normalizer_normalize($filename, Normalizer::FORM_C);
    $files = scandir($dir);

    foreach ($files as $value) {
        // 标准化当前扫描到的文件名，统一编码后再做匹配
        $normalizedValue = normalizer_normalize($value, Normalizer::FORM_C);
        $currentPath = realpath($dir . '/' . $value);

        if (!is_dir($currentPath)) {
            if ($normalizedTarget === $normalizedValue) {
                return $currentPath;
            }
        } elseif ($value != "." && $value != "..") {
            // 接住递归返回值，匹配到目标直接向上传递
            $recursiveResult = getFileInContents($currentPath, $filename);
            if ($recursiveResult) {
                return $recursiveResult;
            }
        }
    }

    return null;
}

if (!isset($_GET['f'])) {
    http_response_code(404);
    echo 'File not found';
    exit;
}

// 基于脚本绝对路径定位files目录，避免相对路径解析错误
$rootFileDir = __DIR__ . '/files/';
$matchedPath = getFileInContents($rootFileDir, $_GET['f']);

if (!$matchedPath) {
    http_response_code(404);
    echo 'File not found';
    exit;
}

// 二进制文件输出逻辑，替换原有的include_once调用
$mime = mime_content_type($matchedPath);
header('Content-Type: ' . $mime);
header('Content-Length: ' . filesize($matchedPath));

// 清理所有输出缓冲，直接输出文件流
while (ob_get_level()) {
    ob_end_clean();
}
readfile($matchedPath);
exit;

• 如果PHP环境未开启intl扩展提供的normalizer函数，可安装对应扩展后再运行，该扩展是Linux下适配多语言文件名的标配组件
• 如果files目录是从Windows环境迁移、或通过Samba挂载的其他编码来源（如GBK编码），需要在扫描文件名时额外做编码转换，将采集到的目录名转为UTF-8后再参与匹配
• 前端传递的文件名参数建议全程做URL编码，后端接收后解码，减少传输过程中的编码丢失问题
• 不要在输出PDF前添加多余的HTML/字符串内容，否则会导致PDF文件损坏无法打开

内容的提问来源于stack exchange，提问作者Cava