---

name: linebot-setup description: LINE Bot Messaging API 設定與除錯指南。包含 LINE Developers Console 設定、Webhook URL 配置、SSL 憑證要求、常見錯誤排解。當用戶需要：(1) 建立新的 LINE Bot、(2) 設定 Webhook URL、(3) 排解 SSL 連線錯誤、(4) 排解 LINE Bot 無回應問題時使用此 skill。

LINE Bot Messaging API 設定指南

快速檢查清單

設定 LINE Bot 前，確認以下條件：

1. SSL 憑證: 必須是有效的 CA 簽發憑證（不接受自簽憑證）
2. 憑證鏈完整: 使用 fullchain.pem，不只是 cert.pem
3. 非 Cloudflare 代理: LINE 可能無法連接 Cloudflare 代理的網域
4. PHP 7.0+: 若使用 PHP，需支援 ?? 運算子
5. 回應時間: Webhook 必須在數秒內回應 200 OK

設定流程

1. LINE Developers Console 設定

1. 前往 https://developers.line.biz/console/
2. 建立 Provider（若無）
3. 建立 Messaging API Channel
4. 記錄：
   • Channel ID
   • Channel Secret（Basic settings）
   • Channel Access Token（Messaging API → Issue）

2. Webhook 設定

在 Messaging API 頁籤：

1. 設定 Webhook URL: https://your-domain.com/webhook.php
2. 開啟 Use webhook（綠色開關在右邊）
3. 點擊 Verify 測試連線

3. 關閉自動回應

在 LINE Official Account Manager（從 Console 連結）：

1. 進入「回應設定」
2. 關閉「自動回應訊息」
3. 關閉「加入好友的歡迎訊息」（如不需要）

常見錯誤排解

SSL connection error

症狀: Verify 按鈕顯示 "An SSL connection error occurred"

檢查步驟:

Copy# 檢查憑證是否為 CA 簽發
openssl s_client -connect your-domain.com:443 -servername your-domain.com 2>/dev/null | openssl x509 -noout -issuer

# 應顯示 Let's Encrypt、DigiCert 等，不是 self-signed

# 檢查憑證鏈完整性
openssl s_client -connect your-domain.com:443 -servername your-domain.com 2>/dev/null | grep -E "Certificate chain|depth="

# 應顯示 depth=0, depth=1, depth=2（完整鏈）

解決方案:

• 自簽憑證 → 取得 Let's Encrypt 憑證（見 references/ssl-letsencrypt.md）
• 憑證鏈不完整 → 使用 fullchain.pem 而非 cert.pem
• Cloudflare 代理 → 使用直連 IP 的網域

Webhook 無回應（僅顯示已讀）

症狀: 發送訊息後只顯示已讀，無 Bot 回應

檢查步驟:

Copy# 檢查 Webhook 是否收到請求
tail -f /path/to/webhook/debug.log

# 檢查 PHP 錯誤日誌
tail -f /var/log/apache2/error.log

常見原因:

1. LINE 自動回應未關閉 → 到 Official Account Manager 關閉
2. PHP 版本過低 → 確認 PHP 7.0+
3. Webhook 回傳 500 → 檢查 PHP 錯誤日誌
4. 簽名驗證失敗 → 確認 Channel Secret 正確

HTTP 500 錯誤

檢查 PHP 版本相容性:

Copy# 檢查 PHP 版本
php -v

# 若使用 ?? 運算子，需 PHP 7.0+
# PHP 5.x 不支援：$var = $array['key'] ?? 'default';
# 改用：$var = isset($array['key']) ? $array['key'] : 'default';

HTTP 401 Authentication failed

症狀: LINE API 回傳 {"message":"Authentication failed..."}

原因: Channel Access Token 無效或過期

解決方案:

1. 前往 LINE Developers Console
2. 進入 Messaging API 頁籤
3. 點擊 Issue 或 Reissue 產生新 Token
4. 更新 config.php 中的 LINE_CHANNEL_ACCESS_TOKEN

Flex Message 圖片不顯示

症狀: 題目或解答應該有圖片但沒有顯示

檢查步驟:

Copy# 確認圖片 URL 可訪問
curl -sI "https://your-domain.com/images/filename.png" | head -3
# 應顯示 HTTP/1.1 200 OK

# 確認圖片目錄存在
ls -la /path/to/images/

常見原因:

1. 圖片檔案不存在 → 檢查檔案是否已上傳
2. URL 路徑錯誤 → 確認 JSON 中的 URL 與實際路徑一致
3. 重複加上 BASE_URL → 如果 JSON 已是完整 URL，程式碼不應再加前綴

修正程式碼:

Copy// 判斷是否為完整 URL
$imageUrl = (strpos($q['question_image'], 'http') === 0)
    ? $q['question_image']
    : IMAGE_BASE_URL . '/' . $q['question_image'];

參考資源

• SSL 憑證取得流程：references/ssl-letsencrypt.md
• Webhook PHP 範例：references/webhook-example.md
• LINE 官方文件：https://developers.line.biz/en/docs/messaging-api/