PHP file_exists() 判斷中文文件名失效的根因分析與解決方案

問題現象

在 UTF-8 編碼的 PHP 腳本中，使用 file_exists() 或 is_file() 檢查包含中文的文件名/路徑時，明明文件存在卻返回 false。例如：

<?php
$filename = '中文文檔.txt'; // 文件實際存在於同目錄
var_dump(file_exists($filename)); // 輸出 bool(false) - 錯誤！

根本原因

文件系統編碼與 PHP 腳本編碼不一致。

• PHP 內部字符串編碼取決於腳本文件編碼（現代項目多為 UTF-8）。
• Windows 文件系統（NTFS）內部使用 UTF-16，但 **PHP 文件系統函數在 Windows 上實際接收的是系統當前代碼頁（ANSI Code Page，通常為 GBK/CP936）編碼的字節流**。
• Linux/Unix 文件系統（ext4/xfs 等）將文件名視為字節序列，無編碼概念；若掛載參數正確，通常直接支持 UTF-8。

因此，在 **Windows + PHP** 環境下，UTF-8 字符串直接傳給 file_exists() 會導致編碼不匹配，無法定位文件。

解決方案

方案一：運行時編碼轉換（Windows 專用）

<?php
$filename = '中文文檔.txt';
// 將 UTF-8 轉為系統代碼頁（GBK/CP936）
$filesystemPath = iconv('UTF-8', 'GBK//IGNORE', $filename);
var_dump(file_exists($filesystemPath)); // bool(true)

// 通用封裝函數
function fs_exists($path) {
    if (DIRECTORY_SEPARATOR === '\\') { // Windows
        $path = iconv('UTF-8', 'GBK//IGNORE', $path);
    }
    return file_exists($path);
}

方案二：統一使用 URL 編碼路徑（跨平台）

利用 rawurlencode() 將路徑各段編碼，配合 file:// 協議（PHP 內部會正確解碼）：

<?php
function fs_exists_universal($path) {
    // 分割目錄與文件名，分別編碼
    $dir = dirname($path);
    $base = basename($path);
    $encodedPath = $dir . '/' . rawurlencode($base);
    return file_exists($encodedPath);
}

// 或更簡單：PHP 7.1+ 支持 file:// 協議自動處理
$url = 'file://' . rawurlencode($absolutePath);
var_dump(file_exists($url));

方案三：目錄掃描對比（兜底方案）

不依賴編碼轉換，讀取目錄列表逐個對比（性能較差，僅適用於極少量文件）：

<?php
function fs_exists_scan($dir, $targetName) {
    $files = scandir($dir);
    foreach ($files as $file) {
        if ($file === $targetName) return true;
        // 或比對 UTF-8 轉換後的名稱
        if (DIRECTORY_SEPARATOR === '\\') {
            if (iconv('GBK', 'UTF-8//IGNORE', $file) === $targetName) return true;
        }
    }
    return false;
}

最佳實踐建議

1. 源頭規避：堅決不使用中文文件名。採用 UUID、時間戳、哈希值、英文標識符命名文件（如 20240115_abc123ef.txt），元數據（原始名稱、上傳者等）存入數據庫。這是**最根治、性能最好、跨平台零問題**的方案。
2. 配置 PHP 環境：Windows 下在 php.ini 設置 internal_encoding = UTF-8、default_charset = UTF-8，但**不改變文件系統層面編碼行為**，仍需轉換。
3. 統一封裝文件系統層：項目中建立 Filesystem 工具類，封裝 exists()、read()、write()、delete() 等方法，內部自動處理編碼轉換，業務代碼始終使用 UTF-8 路徑。
4. 容器化部署：Docker 容器掛載卷時指定編碼選項，或直接在 Linux 容器中運行 PHP，文件系統天然支持 UTF-8，徹底規避 Windows 文件系統編碼坑。

擴展：相關函數同樣受影響

總結

file_exists() 中文失效本質是 **Windows 文件系統 API 要求 ANSI (GBK) 編碼參數**，而 PHP 腳本為 UTF-8。解決路徑依次為：業務層面禁用中文文件名 > 封裝層自動轉碼 > 運行時臨時轉換。現代雲原生部署建議直接使用 Linux 環境（含容器），從基礎設施層面消除編碼差異，讓 PHP 專注於業務邏輯而非編碼糾纏。