背景

我好幾次在用 ThinkPHP 8 新建項目中遇到坑，thinkphp8 中Session 功能默認是關閉的，需要在 middleware.php 文件中手動開啓 \think\middleware\SessionInit::class 中間件。但是middleware.php 文件在項目中存在兩個位置：

• config/middleware.php
• app/middleware.php

新建項目時容易混淆這兩個文件的位置，導致 Session 功能無法正常啓用。本文主要是記錄日誌，避免下次被坑，當然也希望幫助大家避免類似問題。

官方文檔：https://doc.thinkphp.cn/v8_0/session.html

實驗

環境信息

• 框架版本：ThinkPHP 8.0
• PHP 版本：8.1
• 運行環境：WSL下開發

復現步驟

1. 新建項目：

   composer create-project topthink/think tp8

2. 配置 Session：
   按照官方文檔，在 config/middleware.php 文件中添加：

   return [
       \think\middleware\SessionInit::class,
   ];

3. 測試 Session：
   在控制器中編寫測試代碼：

   use think\facade\Session;
   
   class Test
   {
       public function index()
       {
           Session::set('name', 'thinkphp');
           return 'Session set successfully';
       }
   }

4. 觀察結果：

   • 訪問測試接口，頁面返回 "Session set successfully"。
   • 檢查 runtime/session 目錄，發現 沒有生成任何 Session 文件。

排查思路

第一步：確認 Session 配置

• 檢查 config/session.php 文件，確認 Session 配置項無誤：

  return [
      'type'       => 'file',
      'path'       => runtime_path() . 'session',
      'prefix'     => '',
      'expire'     => 1440,
      'var_session_id' => '',
  ];

• 確認 runtime/session 目錄存在且可寫。

第二步：確認中間件加載

• 在 config/middleware.php 中添加日誌輸出，確認中間件是否被加載：

  return [
      function ($request, $next) {
          trace('SessionInit middleware loaded in config/middleware.php');
          return $next($request);
      },
      \think\middleware\SessionInit::class,
  ];

• 查看日誌，發現 沒有相關日誌輸出，説明 config/middleware.php 中的中間件 未被加載。

第三步：確認中間件文件位置

• 查閲官方文檔，發現 全局中間件 應配置在 app/middleware.php 中，而非 config/middleware.php。
• 檢查項目結構，發現 app/middleware.php 文件存在，但 未配置任何中間件。

第四步：修正配置

• 將 \think\middleware\SessionInit::class 移動到 app/middleware.php 文件中：

  return [
      \think\middleware\SessionInit::class,
  ];

• 清除緩存並重啓服務：

  php think clear

• 再次訪問測試接口，觀察 runtime/session 目錄，發現 生成了新的 Session 文件，問題解決。

結果

總結與建議

• 明確中間件配置位置：

  • config/middleware.php：用於配置 應用級別的中間件，通常由框架內部加載。
  • app/middleware.php：用於配置 全局中間件，對所有請求生效。

• 官方文檔提示：

  Session 功能默認關閉，需在 app/middleware.php 中開啓 \think\middleware\SessionInit::class。

• 調試技巧：

  • 使用 trace() 或 Log::record() 記錄中間件加載情況。
  • 檢查 runtime/log 日誌，確認是否有相關錯誤信息。
  • 確認 runtime/session 目錄權限，確保 PHP 有寫入權限。

• 最佳實踐：

  • 新建項目時，優先檢查 app/middleware.php 是否存在。
  • 在團隊開發中，將 Session 配置寫入項目 README，避免重複踩坑。

希望本文能幫助大家快速定位並解決 ThinkPHP 8 中 Session 不生效的問題，避免不必要的調試時間。