PHP Fatal error: session_start(): Failed to initialize storage module: files 徹底解決

錯誤現象

Fatal error: session_start(): Failed to initialize storage module: files (path: ) in /data/www/phpmyadmin/libraries/session.inc.php on line 83

根本原因

PHP 以 files 模組儲存 session，需有效的 session.save_path。錯誤 (path: ) 顯示路徑為**空值**，代表：

1. php.ini 中 session.save_path 被註解或設為空
2. 啟用了 Safe Mode (PHP ≤ 5.3)，限制腳本存取系統預設 /tmp (屬主 root:root)，導致無法寫入
3. 多專案共用主機，各專案需隔離 session 目錄

排查步驟

1. 確認 php.ini 實際生效值

<?php phpinfo(); ?>
搜尋: session.save_path, session.save_handler, safe_mode

2. 測試腳本驗證權限

<?php
// test_session.php
ini_set('display_errors', 1);
error_reporting(E_ALL);
$r = session_start();
var_dump($r); // bool(true) 正常；bool(false) 或 Fatal error 失敗
?>

3. 檢查目錄權限

ls -ld /tmp
# drwxrwxrwt  root root  ... /tmp  (正常應有 sticky bit t)

ls -ld /var/lib/php/session
# 權限應為 700 或 770，擁有者 = php-fpm 使用者 (如 www-data)

解決方案

方案一：專案獨立 session 目錄 (最推薦)

# 1. 建立目錄並設定權限
mkdir -p /data/www/session
chown www-data:www-data /data/www/session
chmod 700 /data/www/session

# 2. 在專案啟動檔 (如 index.php、bootstrap.php) 最早處呼叫
session_save_path('/data/www/session');
session_start();

關鍵點：必須用 session_save_path() 函數，**不可**用 ini_set('session.save_path', ...) (對 files handler 無效)。

方案二：修改 php.ini (全域生效)

; /etc/php/8.1/fpm/php.ini
session.save_handler = files
session.save_path = "/var/lib/php/session"
; 重載 php-fpm
systemctl reload php-fpm

方案三：關閉 Safe Mode (舊版 PHP)

; php.ini
safe_mode = Off
; 重載服務

⚠️ PHP 5.4+ 已移除 Safe Mode，此方案僅適用舊版遺留系統。

方案四：改用 Redis/Memcached (分散式/高併發)

; php.ini
session.save_handler = redis
session.save_path = "tcp://127.0.0.1:6379?auth=yourpass&database=0"
; 需安裝 php-redis 擴充套件

實戰案例：phpMyAdmin 修復

原始碼位置：libraries/session.inc.php

<?php
// 修改前
$r = session_start();

// 修改後：在 session_start() 前指定專屬路徑
$sessionPath = '/data/www/session';
if (is_dir($sessionPath) && is_writable($sessionPath)) {
    session_save_path($sessionPath);
} else {
    // 兜底：嘗試建立
    @mkdir($sessionPath, 0700, true);
    @chown($sessionPath, 'www-data'); // 需權限
    session_save_path($sessionPath);
}

$r = session_start();
if ($r !== true) {
    // 錯誤處理...
}
?>

避坑指南

驗證修復

<?php
session_save_path('/data/www/session');
session_start();
$_SESSION['test'] = 'ok';
echo session_id(); // 輸出 session id 即成功
// 瀏覽器開發者工具 Application > Cookies > PHPSESSID 應有值
?>