Laravel Route 解析頁面錯誤？三步驟快速排查！

更新於 分類於 閱讀次數：

前言

筆者在 Laravel 開發 API 應用時，

有遇到 Route 無法正常解析，導致網頁導向請求一直失敗的情況。

那時候真的是摸不清問題在哪，於是便有了整理此篇文章的想法，

這篇文章將針對 路由無法正常運作 問題，提供 3 個排查步驟，希望能幫到同樣有困難的人。

排查步驟

以可能發生的問題做進一步檢查，可分成以下項目

檢查 api.php 是否能夠解析請求

首先確認 API 路由 (routes/api.php) 是否正確被 Laravel 載入，
可以使用 Artisan 指令列出所有已註冊的路由：

1
php artisan route:list --except-hidden

這個指令會列出所有可用的 API 路由，如果 API 路由沒有出現在列表中，可能有以下的問題：

  • 未定義正確的 API 路由

    請確保 routes/api.php 檔案內有適當的路由。例如： 

    1
    2
    3
    4
    5
    use Illuminate\Support\Facades\Route;

    Route::get('/test', function () {
        return response()->json(['message' => 'API 路由正常運作']);
    });

  • 請求 URL 是否包含 /api 前綴？

    Laravel 預設會將 api.php 內的路由加上 /api 前綴，例如： 

    1
    2
    正確：GET http://yourdomain.com/api/test
    錯誤：GET http://yourdomain.com/test

    如果不希望有 /api，可以修改 RouteServiceProvider.php

檢查 RouteServiceProvider.php 是否正確載入 API 路由

Laravel 的 RouteServiceProvider 負責載入所有的路由檔案，

其中 mapApiRoutes() 方法應該確保 api.php 正確載入。

請開啟 app/Providers/RouteServiceProvider.php，找到 mapApiRoutes() 方法，確認內容如下：

1
2
3
4
5
6
protected function mapApiRoutes()
{
    Route::middleware('api')
        ->prefix('api')
        ->group(base_path('routes/api.php'));
}
  • 確認 prefix('api') 是否正確設定
  • 檢查 middleware('api') 是否存在
  • 確認 group(base_path('routes/api.php')) 指向正確路徑

如果有做任何修改，請執行以下指令清除快取並重新載入路由：

1
2
3
php artisan route:clear
php artisan cache:clear
php artisan config:clear

檢查 .htaccess 是否正確導向請求

如果使用的是 Apache 伺服器，Laravel 需要 .htaccess 來將所有請求導向 public/index.php。

確認 public/.htaccess 檔案是否存在，內容如下：

1
2
3
4
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

如果 .htaccess 不存在，可能導致 Laravel 無法正確解析路由，可以手動新增並填入上述內容。

此外也要確保 Apache 伺服器的 mod_rewrite 模組已啟用，

可使用以下指令檢查：

1
apachectl -M | grep rewrite

如果未啟用，
可以在 Apache 設定 (/etc/apache2/apache2.conf 或 /etc/httpd/conf/httpd.conf) 中新增：

1
LoadModule rewrite_module modules/mod_rewrite.so

並重新啟動 Apache：

1
2
sudo systemctl restart apache2
sudo systemctl restart httpd

結論

當 Laravel API 路由無法解析時，可以透過上述的步驟來排查：

若有一步步確認問題點，應該能解決 Laravel 路由無法解析的問題！

如果文章有其他錯誤的地方，也請不吝留言告知 😊