# 錯誤處理與復原 (/zh-Hant/docs/verdent-for-vscode/error-handling/recovery)
> 解讀錯誤並從中復原
***
了解如何解讀、回應與回報錯誤，有助於你在使用 Verdent for VS Code 時維持高效的開發流程。
### 你將學到 [#你將學到]
* 常見的錯誤類型及其成因
* 如何有效解讀錯誤訊息
* 系統化的疑難排解步驟
* 何時該等待、何時該採取行動
* 如何向 Verdent 團隊回報問題
***
## 常見錯誤類型 [#常見錯誤類型]
完整的錯誤文件目前仍在開發中。以下資訊涵蓋最常遇到的錯誤類別。如遇特定錯誤情境，請聯絡 [support@verdent.ai](mailto:support@verdent.ai) 或造訪 Discord 社群。
**伺服器過載錯誤**
* 發生於流量高峰期間
* 暫時性容量限制
* **處理方式**：等待 5-10 分鐘後重試
**內部伺服器錯誤**
* 後端處理問題
* 暫時性服務中斷
* **處理方式**：稍候並重試，通常會自動恢復
**503 服務無法使用**
* 沒有健康的上游伺服器
* 暫時性基礎設施問題
* **處理方式**：等待服務恢復
**速率限制錯誤**
* 超出請求配額
* API 節流保護
* **處理方式**：等待速率限制重置，降低請求頻率
* 憑證無效或已過期
* 工作階段逾時問題
* **處理方式**：透過 User Center 重新驗證，確認方案處於有效狀態
* 網路連線問題
* 防火牆或 VPN 阻擋連線
* 企業網路限制
* **處理方式**：檢查網路連線，嘗試切換不同網路
* 設定或偏好無效
* 設定檔損毀
* **處理方式**：檢視最近的設定變更，確認設定正確
* 檔案系統權限不足
* 工作區存取限制
* **處理方式**：檢查檔案／資料夾權限，確認工作區存取權
***
## 解讀錯誤訊息 [#解讀錯誤訊息]
詳細的錯誤訊息解讀指南仍在開發中。如遇特定錯誤訊息，請使用 Feedback 按鈕或 Discord 社群尋求協助。
伺服器端錯誤屬於暫時性，通常等待後即可恢復。除了幾分鐘後重試之外，無需採取其他行動。
**留意這些關鍵字：**
* 「Overloaded」或「at capacity」
* 「Internal server error」或「backend processing」
* 「503 Service Unavailable」或「no healthy upstream」
* 「Rate limit」或「quota」
**該怎麼做：**
* 等待 5-10 分鐘後再重試
* 繼續進行本機開發工作
* 檢視目前已做的程式碼變更
* 將目前工作提交至 Git
**一般原則：** 若錯誤訊息提到伺服器狀態、容量或速率限制，即屬暫時性問題。這些是會自動恢復的基礎設施問題。
暫時性伺服器錯誤（502、503、504）通常會在幾分鐘內恢復。請等待 2-3 分鐘後再重試。
**何時需要升級處理：**
* 錯誤持續超過 15 分鐘
* 至 Discord 查看是否有故障回報
* 留意狀態頁面的更新
用戶端錯誤需要你採取行動。這類錯誤不會因等待而自行解決。
**留意這些徵兆：**
* 與驗證或憑證相關的訊息
* 設定或偏好錯誤
* 檔案權限錯誤
* 網路連線失敗
**該怎麼做：**
* **驗證錯誤**：透過 User Center 重新驗證，確認方案處於有效狀態
* **設定錯誤**：檢視最近的設定變更，確認設定檔正確
* **權限錯誤**：檢查檔案／資料夾權限，確認工作區存取權
* **網路錯誤**：測試網際網路連線，嘗試切換不同網路，檢查 VPN／防火牆
**一般原則：** 若錯誤提到驗證、設定、權限或本機設定，你就必須採取修正行動。
**疑難排解步驟：**
1. 完整閱讀錯誤訊息以取得具體指引
2. 辨識是哪個元件回報錯誤（驗證、設定、權限、網路）
3. 依錯誤類型採取對應行動
4. 重試原本的操作以驗證是否修復
### 閱讀錯誤上下文 [#閱讀錯誤上下文]
當錯誤發生時：
1. **完整閱讀錯誤訊息** — 不要略過細節
2. **記下錯誤代碼** — 特定代碼有助於診斷問題
3. **辨識元件** — 是哪個系統回報了錯誤（伺服器、API、本機）
4. **檢查發生時機** — 是立即發生，還是延遲後才出現？
***
## 系統化疑難排解 [#系統化疑難排解]
當 Verdent 出現非預期行為時，請依下列循序漸進的步驟處理，從干擾最小的動作開始。
### 初步回應 [#初步回應]
確認該行為是持續發生還是間歇出現。記下是哪個動作觸發了非預期行為。不要立即假設出了問題 — 許多狀況都是暫時性的。
重新啟動 Verdent for VS Code（關閉並重新開啟 VS Code）。通常可解決卡住的狀態或效能問題。這是最簡單的第一個疑難排解步驟。
### 循序漸進的疑難排解 [#循序漸進的疑難排解]
若基本重新啟動無法解決問題：
請依序執行系統化疑難排解步驟，跳過步驟往往會錯過根本原因。
用其他網站測試網際網路連線。改用不同網路（手機熱點）以排除防火牆／VPN 問題。確認企業網路是否阻擋了連線。
確認你仍處於已驗證狀態。在 User Center 確認方案處於有效狀態。檢視最近可能影響行為的設定變更。
至 Discord 社群查看是否有類似回報：[https://discord.com/invite/NGjXEZcbJq。使用](https://discord.com/invite/NGjXEZcbJq。使用) Feedback 按鈕回報問題。請附上非預期行為的描述與重現步驟。
### 不該做的事 [#不該做的事]
對於暫時性問題，請避免下列動作：
* 不要立即重新安裝 Verdent
* 不要清除 VS Code 快取或應用程式資料
* 不要為了暫時性問題而修改系統設定
* 除非其他應用程式也受影響，否則不要重新啟動電腦
在 Manual Accept Mode 下，未仔細檢視確切指令前，切勿核可破壞性操作（rm、DROP、DELETE）。
**為什麼？** 這些動作耗時且很少能解決問題。多數問題只要簡單重新啟動，或等待暫時性伺服器問題排除即可解決。
***
## 何時等待、何時行動 [#何時等待何時行動]
了解該等待還是採取行動，可避免浪費疑難排解的精力。
這些錯誤會自動恢復 — 除了等待並重試外無需採取任何行動。
**伺服器過載或容量錯誤：**
* 「Overloaded」或「at capacity」訊息
* 流量高峰期間
* 暫時性服務中斷
**速率限制：**
* 「Rate limit」或「quota exceeded」訊息
* 短時間內請求過多
* API 節流保護
**間歇性連線問題：**
* 偶發的失敗請求，重試後即成功
* 網路短暫不順
* 短暫連線中斷
**等待期間可以做的事：**
* 繼續進行本機開發工作
* 檢視目前已做的程式碼變更
* 規劃後續步驟或待辦事項
* 將目前工作提交至 Git
**該等多久：**
* 標準等待時間：5-10 分鐘
* 若 10 分鐘後仍失敗，轉為疑難排解
* 至 Discord 查看是否有大範圍問題的回報
這些錯誤不會因等待而解決 — 你必須採取修正行動。
**驗證失敗：**
* 工作階段已過期 → 透過 User Center 重新驗證
* 憑證無效 → 確認方案處於有效狀態
* 需要重新驗證 → 檢查 User Center
**持續性錯誤（10 分鐘以上）：**
* 多次重試後仍重複出現相同錯誤 → 開始疑難排解
* 一致的失敗模式 → 檢查設定
* 重新啟動後錯誤依舊 → 驗證環境
**設定問題：**
* 最近變更過設定 → 檢視並還原變更
* 全新設定或安裝 → 確認設定檔
* 變更過網路環境 → 測試連線
**權限錯誤：**
* 檔案系統存取被拒 → 檢查檔案／資料夾權限
* 工作區限制 → 確認工作區存取權
* 資料夾權限 → 授予必要權限
**網路問題：**
* 完全無法連線 → 測試網際網路連線
* VPN 或防火牆阻擋 → 嘗試切換不同網路
* 企業網路限制 → 聯絡 IT 支援
**判斷原則：**
* 伺服器／速率錯誤 → 等待
* 驗證／設定／權限／網路 → 立即行動
* 不確定？ → 先等待 5-10 分鐘，若持續再行動
***
## 提供錯誤上下文 [#提供錯誤上下文]
在尋求協助或回報問題時，請附上完整的上下文以加速診斷。
### 必要資訊 [#必要資訊]
**錯誤細節：**
* 確切的錯誤訊息文字（直接複製貼上，不要意譯）
* 錯誤代碼（若有提供）
* 錯誤發生的時間戳記
* 發生頻率（一次性、間歇性、持續性）
**環境：**
* Verdent for VS Code 版本
* VS Code 版本
* 作業系統與版本
* 網路環境（家用、企業、VPN）
**重現步驟：**
1. 你當時想做什麼
2. 使用的確切提示詞或指令
3. 涉及的檔案或上下文
4. 錯誤發生前所採取的動作
**上下文：**
* 你當時使用的執行模式
* 工作區的規模與複雜度
* 最近的設定變更
* 先前成功的類似操作
### 錯誤回報範例 [#錯誤回報範例]
良好的錯誤回報格式：
```
Issue: Getting "Internal server error" when requesting code analysis
Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."
Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)
Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request
Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally
```
### 為什麼這樣有效 [#為什麼這樣有效]
* 確切的錯誤訊息文字
* 完整的環境細節
* 清楚的重現步驟
* 與正常情境的對比
* 關於模式的額外上下文
***
## 回報問題 [#回報問題]
**位置：** Verdent 面板的頂部列
**功能：**
* 開啟彈出式覆蓋視窗以提交問題與建議
* 直達 Verdent 團隊的管道
* 最適合回報錯誤與功能請求
**何時使用：**
* 已確認、具備清楚重現步驟的錯誤
* 具備明確使用情境的功能請求
* 需要直接與團隊溝通
* 需要調查的非緊急問題
**應包含內容：**
* 清楚的問題描述
* 錯誤訊息（確切文字）
* 重現步驟
* 預期行為與實際行為
* Verdent 版本與平台
* 問題開始的時間
**連結：** [https://discord.com/invite/NGjXEZcbJq](https://discord.com/invite/NGjXEZcbJq)
**提供的協助：**
* 活躍的 Verdent 使用者與團隊成員社群
* 即時的疑難排解協助
* 可附截圖分享問題
* 從資深使用者取得協助
* 社群討論與替代方案
**何時使用：**
* 需要即時討論的緊急問題
* 需要往返溝通的複雜疑難排解
* 需要社群對最佳做法的意見
* 正式回報前的快速提問
* 與社群分享替代方案
| 問題類型 | 使用 Feedback 按鈕 | 使用 Discord |
| ------------ | :------------: | :--------: |
| 已確認且具重現步驟的錯誤 | ✓ | |
| 功能請求 | ✓ | |
| 需要緊急疑難排解 | | ✓ |
| 需要討論的複雜問題 | | ✓ |
| 快速提問 | | ✓ |
| 想取得社群意見 | | ✓ |
| 正式錯誤回報 | ✓ | |
| 一般協助 | | ✓ |
**不需要回報的內容：**
* 暫時性伺服器錯誤（小於 10 分鐘）
* 流量高峰期間
* 已記錄的已知問題
* 預期內的行為
**改為：** 等待暫時性問題排除、至 Discord 查看近期回報、檢視文件。
***
## 預防最佳實務 [#預防最佳實務]
主動的做法可降低錯誤發生頻率，並在錯誤發生時改善復原效果。
在提示詞中使用具體的措辭並納入相關檔案上下文，可在許多常見錯誤發生前就加以預防。
### 開始工作前 [#開始工作前]
**1. 驗證設定**
* 在 User Center 檢查驗證狀態
* 確認方案處於有效狀態
* 確保網路連線穩定
* 檢視最近的設定變更
**2. 初始化 Git**
* 使用較寬鬆的模式前務必先建立版本控制
* 提交目前工作以取得乾淨的起點
* 在發生問題時提供回復選項
**3. 檢查點數餘額**
* 確認有足夠的點數可完成計畫中的工作
* 如有需要，在開始複雜任務前先儲值
* 避免因點數耗盡而中途中斷
### 開發期間 [#開發期間]
**1. 使用適當的執行模式**
* 不熟悉的程式碼使用 Manual Accept
* 複雜變更使用 Plan Mode
* Auto-Run 僅在有 Git 安全網時使用
* 讓模式與風險程度相符
**2. 監控效能**
* 留意回應品質下降
* 注意回應時間變慢
* 效能下滑時開啟全新工作階段
* 手動追蹤上下文使用量
**3. 清楚、具體的提示詞**
* 減少因誤解請求而產生的錯誤
* 納入相關上下文與限制
* 參考既有的模式
* 明確指定範圍
### 錯誤發生後 [#錯誤發生後]
**1. 從模式中學習**
* 記下觸發錯誤的原因
* 辨識可重現的條件
* 調整工作流程以避開觸發因素
* 與社群分享發現
**2. 記錄替代方案**
* 為有效的解法保留筆記
* 與團隊成員分享
* 貢獻給社群知識庫
* 回報給 Verdent 團隊以修復
**3. 更新設定**
* 依經驗調整設定
* 為你的工作流程進行最佳化
* 設定規則以預防問題
* 維護 AGENTS.md 文件
***
## 延伸閱讀 [#延伸閱讀]
撰寫有效的提示詞以減少錯誤
最佳化上下文以避免效能問題
選擇適當的模式以將風險降至最低