Laravel項目在Linux上的錯誤排查方法

Laravel項目在Linux上的錯誤排查方法

1. 常見基礎問題排查

• 文件權限問題：Laravel的storage（日志、緩存、會話等）和bootstrap/cache（路由/配置緩存）目錄需要正確讀寫權限。推薦使用sudo chown -R www-data:www-data /path/to/project（將www-data替換為你的Web服務器用戶，如nginx、apache）設置所有者，再用sudo chmod -R 755 storage bootstrap/cache賦予讀寫權限。
• .env文件配置：確保項目根目錄存在.env文件（可從.env.example復制生成），并正確配置數據庫連接（DB_CONNECTION、DB_HOST、DB_DATABASE、DB_USERNAME、DB_PASSWORD）、應用密鑰（APP_KEY，可通過php artisan key:generate生成）等參數。
• Composer依賴安裝：運行composer install安裝項目所需依賴；若依賴已安裝但修改了composer.json，需運行composer update更新依賴。
• 應用密鑰生成：若未生成APP_KEY（.env中無APP_KEY或為空），運行php artisan key:generate生成新的密鑰，否則會出現“No application encryption key has been specified”錯誤。
• Web服務器配置：確保Web服務器（Nginx/Apache）指向項目public目錄。Nginx示例配置：root /path/to/project/public; + location / { try_files $uri $uri/ /index.php?$query_string; }；Apache需啟用mod_rewrite并配置AllowOverride All。

2. 日志分析與定位

• 日志文件位置：Laravel日志默認存儲在storage/logs/laravel.log（若未生成，可手動創建目錄并賦予權限），包含錯誤堆棧、請求信息等關鍵內容。
• 實時查看日志：使用tail -f storage/logs/laravel.log實時監控最新日志，快速定位正在發生的錯誤。
• 日志過濾：用grep命令篩選特定錯誤，如grep 'error' storage/logs/laravel.log查看所有錯誤日志，grep 'SQLSTATE' storage/logs/laravel.log篩選數據庫錯誤。
• 日志級別控制：修改.env中的LOG_LEVEL（如ERROR僅記錄錯誤及以上級別，DEBUG記錄詳細調試信息），生產環境建議設為ERROR，開發環境設為DEBUG。
• 日志輪轉配置：使用logrotate防止日志過大，創建/etc/logrotate.d/laravel文件，添加以下內容：

  /path/to/project/storage/logs/*.log {
      daily
      missingok
      rotate 14
      compress
      notifempty
      create 640 www-data adm
  }
  

  表示每天輪轉、保留14天、壓縮舊日志。

3. 常見錯誤類型及解決方案

• 類/文件未找到：檢查類名與命名空間是否匹配（如App\Http\Controllers\UserController對應UserController.php文件），運行composer dump-autoload重新生成自動加載文件。
• 路由問題：確認路由定義正確（如Route::get('/users', 'UserController@index')），清除路由緩存（php artisan route:clear）；若出現MethodNotAllowedHttpException，檢查請求方法（GET/POST/PUT/DELETE）是否與路由定義一致。
• 數據庫錯誤：檢查.env中的數據庫配置是否正確，數據庫服務是否運行（systemctl status mysql）；若出現Table not found，運行php artisan migrate執行遷移創建表。
• PHP版本/擴展問題：Laravel 10需要PHP 8.1及以上版本，運行php -v檢查版本；安裝必要擴展（如php-mysql、php-json、php-curl），可通過sudo apt install php-mysql php-json php-curl（Ubuntu/Debian）或sudo yum install php-mysqlnd php-json php-curl（CentOS/RHEL）安裝。

4. 高級排查工具

• Laravel Telescope：安裝composer require laravel/telescope并通過php artisan telescope:install初始化，提供請求追蹤、異常查看、數據庫查詢分析等功能，幫助深度排查問題。
• 第三方日志管理：集成Monolog、Papertrail或Loggly等工具，實現實時日志監控、搜索和告警，提升日志管理效率。