PHP include 中文路徑報錯的根因與唯一解法

錯誤現象

Warning: unknown: failed to open stream: no such file or directory in unknown on line 0
Fatal error: unknown: failed opening required 'e:/ttttt/中文/index.php' (include_path='.;c:php5pear') in unknown on line 0

明明文件存在，include_path 配置也正確，卻報「無法打開流：沒有該文件或目錄」。

根因分析

PHP 核心在 Windows 下對中文路徑的支持存在缺陷。 當文件路徑包含中文字符時，PHP 內部將路徑編碼傳遞給系統 API 時可能出現編碼轉換錯誤（GBK/UTF-8 混淆），導致系統找不到實際路徑。這是 PHP 歷史遺留問題，非 include_path 配置問題。

唯一徹底解法：杜絕中文目錄/文件名

原則：項目代碼、資源文件、上傳目錄的所有層級路徑，嚴禁出現中文字符。

重構建議

// 錯誤結構
/e:/project/中文目錄/用戶模塊/index.php

// 正確結構
/e:/project/chinese_dir/user_module/index.php
// 或使用拼音/英文單詞
/e:/project/zh_cn/user/index.php

補充：Apache 虛擬目錄可支持中文

僅針對 Apache 2.2+ 配置的虛擬目錄（Alias/DocumentRoot），若將 httpd.conf 保存為 UTF-8 無 BOM 編碼，則可使用中文目錄名。但 PHP 腳本內部的 include/require/fopen 等文件系統操作仍不支持中文路徑。

最佳實踐清單

1. 代碼倉庫：所有目錄、文件命名僅使用小寫字母、數字、下劃線、連字符（[a-z0-9_-]）。
2. 上傳目錄：用戶上傳文件重命名為 UUID/時間戳+隨機數，原文件名存數據庫。
3. 配置文件：httpd.conf、php.ini、.env 等均保存為 UTF-8 無 BOM。
4. 編碼統一：專案全站強制 UTF-8（頁面、數據庫連接、PHP 文件編碼）。

遺留項目緊急遷移腳本（參考）

<?php
// 批量重命名中文目錄/文件為拼音（需安裝 overtrue/pinyin）
require 'vendor/autoload.php';
use Overtrue\Pinyin\Pinyin;

$pinyin = new Pinyin();
$root = '/path/to/project';

$iterator = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator($root, FilesystemIterator::SKIP_DOTS),
    RecursiveIteratorIterator::CHILD_FIRST // 先處理子項，再處理父目錄
);

foreach ($iterator as $file) {
    $basename = $file->getBasename();
    // 簡單判斷是否含中文
    if (preg_match('/[\x{4e00}-\x{9fa5}]/u', $basename)) {
        $newName = $pinyin->permalink($basename, '_'); // 中文轉拼音下劃線
        $newPath = $file->getPath() . DIRECTORY_SEPARATOR . $newName;
        if (!file_exists($newPath)) {
            rename($file->getPathname(), $newPath);
            echo "Renamed: {$basename} -> {$newName}\n";
        }
    }
}
?>

結語

PHP 中文路徑問題已存在十餘年，社區共識是「規避而非修復」。遵循「純 ASCII 路徑」規範，能省去無數排查工時，也是專業項目工程化的基本素養。