告別手刻 OAuth！Laravel 12 x LINE Login 實戰：用 Socialite 實現秒速登入與個資同步 (2026版)

嗨，我是 Eric，浪花科技的資深工程師。如果現在是 2026 年，而你還在用 `cURL` 手動發送 HTTP請求去處理 OAuth 2.0 的 Authorization Code Flow，那我真的得請你喝杯咖啡，好好聊聊你的肝還要不要了。

在台灣，LINE 的滲透率依然是霸主級別。對於我們做 Web 開發的人來說，「使用 LINE 登入」不是一個選項，而是標配。但是，LINE Login 的 API 文件雖然詳細，對於新手來說，要處理 State 驗證、Callback 接收、Access Token 交換，再來個 Refresh Token 機制，真的會讓人寫到懷疑人生。

今天這篇文章，我不講廢話，直接帶你用 Laravel 12（是的，假設你已經升級到最新版）搭配 Laravel Socialite 和 Socialite Providers，優雅、快速地解決 LINE Login 串接。我們會處理掉那些煩人的坑，比如 Email 抓不到、Callback URL 不對應等問題。

為什麼選擇 Socialite 而不是自己寫 API？

這是我在 Code Review 時最常問初階工程師的問題。簡單來說，安全性與維護成本。Socialite 幫你封裝了 OAuth 2.0 的複雜邏輯，自動處理 CSRF 防護（透過 state 參數），並且提供統一的介面。這意味著，如果你哪天老闆突然說要加個 Google 或 Facebook 登入，你的程式碼架構幾乎不用動，只要改改設定檔就好。

第一步：LINE Developers Console 的前置作業

在寫 Code 之前，請先確保你的 LINE Login Channel 設定正確。這一步錯了，後面寫再好的 Code 都是 400 Bad Request。

• 登入 LINE Developers Console。
• 建立一個新的 Provider 和 Channel (類型選 LINE Login)。
• 關鍵設定： 在「LINE Login」頁籤下，找到 Callback URL。
• 若是本機開發，請填入：`http://localhost:8000/auth/line/callback` (請依你的實際開發網址調整)。
• 取得權限： 如果你需要使用者的 Email，請到「OpenID Connect」區塊申請 Email 權限（這在 2026 年依然嚴格，需要截圖證明你的 UI 有告知使用者）。

第二步：安裝套件與設定

Laravel 原生的 Socialite 預設支援 Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, Bitbucket。要在 Laravel 中使用 LINE，我們需要社群維護的 socialiteproviders/line。

打開你的終端機：

composer require laravel/socialite
composer require socialiteproviders/line

設定 Config

接著，我們需要註冊 Provider。在 Laravel 11/12 之後，架構變得更精簡，但原理不變。請打開 config/services.php，加入 LINE 的設定：

// config/services.php

return [
    // ... 其他服務

    'line' => [
        'client_id' => env('LINE_CLIENT_ID'),
        'client_secret' => env('LINE_CLIENT_SECRET'),
        'redirect' => env('LINE_REDIRECT_URI'),
    ],
];

別忘了在 .env 檔案中補上你的密鑰：

LINE_CLIENT_ID=你的ChannelID
LINE_CLIENT_SECRET=你的ChannelSecret
LINE_REDIRECT_URI=http://localhost:8000/auth/line/callback

註冊 Event Listener

這是最容易被遺漏的一步！Socialite Providers 需要監聽 SocialiteWasCalled 事件來注入 LINE 的驅動。在 app/Providers/EventServiceProvider.php (或是 Laravel 11+ 的 bootstrap 設定中) 加入：

// 確保引入正確的 namespace
use SocialiteProviders\Manager\SocialiteWasCalled;
use SocialiteProviders\Line\LineExtendSocialite;

protected $listen = [
    SocialiteWasCalled::class => [
        // 這裡是關鍵，告訴 Socialite 我們要用 LINE
        LineExtendSocialite::class.'@handle',
    ],
];

第三步：Controller 實戰開發

現在進入重頭戲。我們需要兩個路由：一個是將使用者「踢」去 LINE 登入頁面，另一個是使用者登入完「跳」回來時的處理。

建立一個 LoginController (或專門的 SocialAuthController)：

php artisan make:controller Auth/LineController

接著，編寫核心邏輯。這裡我會加入一些 2026 年開發者該有的防呆機制，比如 try-catch 捕捉取消授權的情況。

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use Laravel\Socialite\Facades\Socialite;
use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Log;
use Exception;

class LineController extends Controller
{
    /**
     * 重新導向至 LINE 登入頁面
     */
    public function redirectToProvider()
    {
        // 這裡可以透過 with(['bot_prompt' => 'aggressive']) 來強制顯示加好友選項
        return Socialite::driver('line')->redirect();
    }

    /**
     * 處理 LINE 回傳的 Callback
     */
    public function handleProviderCallback()
    {
        try {
            // 獲取使用者資訊
            $lineUser = Socialite::driver('line')->user();
            
            // 為了 debug 方便，開發階段可以 log 下來，上線請移除
            // Log::info('Line User', (array) $lineUser);

            // 這裡我們用 updateOrCreate 來處理登入或註冊
            // 注意：LINE 的 email 不一定會有，取決於使用者有沒有授權
            $user = User::updateOrCreate(
                ['line_id' => $lineUser->getId()], // 搜尋條件
                [
                    'name' => $lineUser->getName(),
                    'email' => $lineUser->getEmail(), // 可能為 null
                    'avatar' => $lineUser->getAvatar(),
                    'password' => bcrypt(str()->random(24)), // 隨機密碼
                    'line_token' => $lineUser->token,
                    'line_refresh_token' => $lineUser->refreshToken,
                ]
            );

            // 登入該使用者
            Auth::login($user, true);

            return redirect()->intended('/dashboard');

        } catch (Exception $e) {
            Log::error('Line Login Error: ' . $e->getMessage());
            return redirect('/login')->with('error', 'LINE 登入失敗，請稍後再試。');
        }
    }
}

第四步：定義路由

在 routes/web.php 中加入這兩行：

use App\Http\Controllers\Auth\LineController;

Route::get('auth/line', [LineController::class, 'redirectToProvider'])->name('auth.line');
Route::get('auth/line/callback', [LineController::class, 'handleProviderCallback']);

2026 開發者必須注意的「坑」

寫了這麼多年 Laravel，這裡有幾個 Eric 的血淚經驗分享：

1. Email 為什麼是空的？

這是最常見的問題。LINE 的 OpenID Connect 預設不提供 Email。你必須先去 LINE Developers Console 申請 `email` scope 權限，並且截圖你的應用程式畫面給 LINE 審核（雖然審核很快，但一定要做）。即使申請過了，使用者在授權頁面如果取消勾選 Email，你的 `$lineUser->getEmail()` 依然會是 null。所以你的資料庫欄位 email 最好設定為 nullable，或是另外設計邏輯強迫使用者補填。

2. State Mismatch 錯誤

如果在測試時一直出現 `InvalidStateException`，通常是因為你的 Session 設定有問題。請檢查 config/session.php 中的 `domain` 設定，或是確認你的瀏覽器沒有因為 Cookie SameSite 策略而擋下了 Session Cookie。

3. 加好友與 Messaging API 的連動

如果你希望使用者登入後，後台能自動發送 LINE 訊息給他，單純的 LINE Login 是不夠的。你需要將 Channel 連動到官方帳號（Official Account）。在程式碼中，使用 `Socialite::driver(‘line’)->with([‘bot_prompt’ => ‘aggressive’])` 可以讓使用者在登入授權頁面時，同時看到「加入好友」的選項。

進階應用：登入後的下一步

登入只是第一步，接下來你可能需要保護你的 API，或者建立自動化的訊息通知系統。這部分可以參考我們之前的技術文章，結合 JWT 與 Chatbot，把使用者價值最大化。

推薦閱讀

• API 像公共廁所隨便進？Laravel 11 JWT 終極實戰：打造駭客絕望的無狀態驗證堡壘 – 登入後取得 Token 才是現代化前後端分離的標準做法。
• LINE Bot 不再只會單向通知！N8N 視覺化工作流實戰，打造你的 AI 智慧客服大腦 – 拿到使用者的 LINE ID 後，結合 n8n 打造更強的互動體驗。
• Laravel 防線告急？手刻驗證 (Validation) 與中介層 (Middleware)，打造駭客也繞道的銅牆鐵壁！ – 確保登入後的使用者資料傳輸安全。

LINE Login 的串接其實不難，難的是如何處理那些「非快樂路徑」（Unhappy Path）的異常狀況。希望這篇教學能幫大家省下 debug 的時間，把時間花在更有創造力的 Vibe Coding 上！