第二章：Terminal 報錯不要慌：如何精準複製錯誤訊息給 AI 讓他一秒認錯

很多人在遇到程式噴紅字的時候，第一反應是「崩潰」，第二反應是「把整個螢幕截圖丟給 AI」。但這其實是非常低效的做法。本章將教你如何像個資深工程師一樣，看懂錯誤訊息，並精準地餵給 AI。

為什麼不要只丟截圖？

雖然現在的 AI（如 GPT-4o, Claude 3.5 Sonnet）視力很好，可以看懂截圖，但截圖有幾個致命缺點：

字數限制：截圖往往只能拍到最後幾行錯誤，真正的「根源（Root Cause）」可能在上面被卡掉了。
無法搜尋：AI 無法直接從截圖中複製特定的變數名稱或檔案路徑，這會增加它猜錯的機率。
缺少堆疊追蹤（Stack Trace）：最關鍵的行號資訊往往在截圖的邊緣。

看懂 Terminal 報錯的三大核心

每次看到 Terminal 噴出一大串紅字，不要害怕，它們其實非常有規律。你只需要尋找三個關鍵字：

1. Error Type（錯誤類型）

通常在最上面或最下面，例如：

TypeError: 型別錯誤（例如試圖讀取 undefined 的屬性）。
ReferenceError: 參考錯誤（變數沒定義就使用）。
SyntaxError: 語法錯誤（少打括號或分號）。
ModuleNotFoundError: 找不到套件（忘記 npm install）。

2. File Path & Line Number（檔案路徑與行號）

這非常重要！錯誤訊息一定會告訴你是哪個檔案的第幾行出錯。例如：at Object.<anonymous> (/src/components/Header.tsx:42:15) 這代表錯誤發生在 Header.tsx 的第 42 行。

3. The Message（錯誤具體訊息）

通常緊接在 Error Type 後面。例如：Cannot read properties of undefined (reading 'map')

實戰：如何精準複製給 AI？

遇到錯誤時，請停止恐慌，按照以下步驟操作：

步驟一：滑動到錯誤的最開頭

很多時候，你看到的最後一行只是一堆連鎖反應的結果。往上滾動 Terminal，找到第一行噴出 Error: 的地方。

步驟二：複製完整的 Stack Trace

把從錯誤發生，到最後一行的堆疊資訊「完整複製」下來。

步驟三：加上下文 Prompt

單純丟錯誤訊息給 AI 常常會得到瞎猜的答案。最完美的 Prompt 應該長這樣：

[我剛剛做了什麼] 我剛剛在 src/app/page.tsx 裡面引入了 Supabase 的 vt_profiles 資料，想要用 map 渲染出列表。

[出現的錯誤訊息]
TypeError: Cannot read properties of undefined (reading 'map')
    at Page (src/app/page.tsx:25:20)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:16305:18)
[相關的程式碼 (src/app/page.tsx)]
export default function Page() {
  const { data: profiles } = useSupabaseProfiles();
  return (
    <div>
      {profiles.map(p => <div key={p.id}>{p.name}</div>)}
    </div>
  )
}
請問為什麼會出現這個錯誤？我該如何加上保護機制？

AI 一秒認錯並修復

當你提供這樣精準的 Context 時，AI 會立刻告訴你：「啊！因為 profiles 在資料還沒載入完成時是 undefined，所以你不能直接呼叫 .map()。你需要加上可選串連（Optional Chaining） profiles?.map(...) 或者是加上 Loading 狀態檢查。」

常見的新手地雷

以為 Warning 是 Error：黃色的 Warning 不會讓程式崩潰，紅色的 Error 才會。不要把 Warning 丟給 AI 叫它「修復網頁白屏」，這會誤導它。
只給報錯不給程式碼：AI 不是通靈王，如果你不貼上對應的程式碼，它只能給你「教科書式」的模糊建議。
環境變數沒抓到：如果你看到 NEXT_PUBLIC_API_KEY is undefined，通常是因為你忘了重啟開發伺服器（npm run dev），AI 再怎麼改程式碼都沒用。這時候重啟才是解藥！

學會看懂並精準投餵 Terminal 錯誤訊息，是你從 Vibe Coding 新手邁向高手的必經之路！

🔍 深入解讀錯誤訊息

錯誤訊息的五個關鍵資訊

| 資訊 | 範例 | 意義 | |------|------|------| | 錯誤類型 | TypeError, SyntaxError | 告訴你問題的性質 | | 檔案路徑 | src/app/api/auth/route.ts:15 | 哪個檔案、哪一行 | | 錯誤描述 | Cannot read properties of undefined | 具體什麼問題 | | 堆疊追蹤 | at fetchUser (api.ts:23) | 呼叫順序 | | 程式碼片段 | return user.name.toUpperCase() | 當前行附近的程式碼 |

如何用 AI 分析錯誤

❌ 錯誤方式：
「我這邊報錯了，幫我看看」

✅ 正確方式：
「我在 Next.js 14 App Router 中，執行 npm run build 時出現以下錯誤：
[貼上完整錯誤訊息]
這個錯誤是在我新增 middleware.ts 之後出現的。
我的 auth.ts 設定如下：[貼上程式碼]」

常見錯誤分類

| 類別 | 特徵 | 最常見原因 | 解決方向 | |------|------|-----------|---------| | Build Error | npm run build 失敗 | TypeScript 型別錯誤、未處理的 Promise | 檢查型別與 async/await | | Runtime Error | 瀏覽器 Console 紅字 | undefined 取值、API 回傳格式不符預期 | 加 console.log 逐步確認 | | Hydration Error | Next.js 特有的報錯 | 伺服器端與客戶端 HTML 不一致 | 檢查 useEffect、typeof window | | 404 Error | API 回傳 404 | 路由對應錯誤、檔案不存在 | 檢查檔案結構與路由命名 | | CORS Error | 瀏覽器阻擋跨域請求 | 後端未設定 Access-Control-Allow-Origin | 在 API Gateway 或 middleware 設定 CORS |

關鍵要點

✅ Vibe Coding = 用自然語言描述需求，AI 生成程式碼
✅ 精準的 Prompt = 角色 + 目標 + 格式 + 約束
✅ AI 鬼打牆時：打斷重來 > 繼續糾纏
✅ .cursorrules / CLAUDE.md 是規範 AI 行為的關鍵
✅ Terminal 報錯訊息是 AI 除錯最重要的線索

Prompt 框架

角色：你是一個 [資深 Python 工程師]
目標：[幫我建立一個 FastAPI 使用者 CRUD API]
格式：[回傳完整的 Python 程式碼]
約束：[使用 Pydantic v2, SQLAlchemy async, PostgreSQL]

🛠️ 建立你的除錯 SOP

當你遇到錯誤時，依照以下 SOP 操作，可以在最短時間內解決問題：

Step 1: 讀懂錯誤

仔細看 Terminal 輸出的第一行——錯誤類型是什麼？檔案路徑是哪個？

Step 2: 複製完整錯誤

不要只複製「紅字的部分」，要複製從頭到尾的完整輸出。錯誤訊息下半段的 Stack Trace 往往才是關鍵。

Step 3: 隔離問題

在請 AI 幫忙之前，先自己確認：

這個錯誤是固定的還是隨機的？（重跑一次看會不會出現）
這個錯誤是在新增什麼功能後出現的？（用 git diff 查看變更）
這個錯誤只發生在某個特定操作嗎？

Step 4: 給 AI 完整的上下文

❌ 這樣 AI 無法精準回答：
「我報錯了，TypeError: Cannot read properties of undefined」

✅ 這樣 AI 可以一秒定位問題：
「我在 pages/products/[id].tsx 第 23 行遇到 TypeError: Cannot read properties of undefined (reading 'name')。
這個檔案是我在新增產品詳細頁面時建立的，
錯誤發生在 `return product.name.toUpperCase()` 這一行。
product 是從 useRouter().query.id 取得的參數去 API 抓回來的。
我的 API 回傳格式是 { data: Product | null }。
請問為什麼 product 會是 undefined？」

除錯 SOP 流程圖

報錯發生
    │
    ▼
Step 1: 讀錯誤類型 & 檔案路徑
    │
    ▼
Step 2: 複製完整錯誤訊息 (含 Stack Trace)
    │
    ▼
Step 3: 確認觸發條件 (新增了什麼？操作了什麼？)
    │
    ▼
Step 4: 給 AI 完整上下文 (檔案 + 錯誤 + 相關程式碼)
    │
    ▼
AI 給出解答
    │
    ▼
Step 5: 驗證修復 (npm run build + 手動測試)

console.log 除錯：最簡單也最有效

為什麼 console.log 還不夠？

// ❌ 只寫 console.log 的問題：
console.log(data);  // 不知道這個 data 是哪個變數
console.log(data);  // 多個 log 分不清楚誰是誰

// ✅ 加上標籤
console.log('API response:', data);
console.log('after filter:', filtered);

// ✅ 用條件式 log 減少雜訊
if (user.role === 'admin') {
  console.log('Admin action:', action);
}

更好的除錯方式

| 方法 | 使用時機 | 優點 | |:----|:--------|:----| | console.log | 快速確認變數值 | 最快，適合開發初期 | | 中斷點（Breakpoint） | 需要觀察執行流程 | 不修改程式碼 | | React DevTools | React Component 狀態 | 專攻 React |

下一章預告：瀏覽器 DevTools

console.log 只能看到你主動輸出的資訊。下一章的瀏覽器 DevTools 可以讓你看見所有網路請求、DOM 狀態、效能瓶頸。