docs: improve zh-cn and zh-tw documentation translations (#13942)
This commit is contained in:
@@ -1,67 +1,67 @@
|
||||
---
|
||||
title: 疑難排解
|
||||
description: 常見問題以及如何解決它們。
|
||||
description: 常見問題及其解決方法。
|
||||
---
|
||||
|
||||
要除錯 opencode 問題,請首先檢查其儲存在磁碟上的日誌和本地數據。
|
||||
要偵錯 OpenCode 的問題,請先檢查其儲存在磁碟上的日誌和本地資料。
|
||||
|
||||
---
|
||||
|
||||
## 日誌
|
||||
|
||||
日誌檔案寫入:
|
||||
日誌檔案寫入位置:
|
||||
|
||||
- **macOS/Linux**:`~/.local/share/opencode/log/`
|
||||
- **Windows**:按 `WIN+R` 並貼上 `%USERPROFILE%\.local\share\opencode\log`
|
||||
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
||||
- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.local\share\opencode\log`
|
||||
|
||||
日誌檔案以時間戳命名(例如 `2025-01-09T123456.log`),並保留最近的 10 個日誌檔案。
|
||||
日誌檔案以時間戳記命名(例如 `2025-01-09T123456.log`),並保留最近的 10 個日誌檔案。
|
||||
|
||||
您可以使用 `--log-level` 命令列選項設定日誌等級以獲取更詳細的除錯資訊。例如,`opencode --log-level DEBUG`。
|
||||
你可以透過 `--log-level` 命令列選項設定日誌等級以取得更詳細的偵錯資訊。例如:`opencode --log-level DEBUG`。
|
||||
|
||||
---
|
||||
|
||||
## 儲存
|
||||
|
||||
opencode 將工作階段數據和其他應用程式數據儲存在磁碟上:
|
||||
OpenCode 將工作階段資料和其他應用程式資料儲存在磁碟上:
|
||||
|
||||
- **macOS/Linux**:`~/.local/share/opencode/`
|
||||
- **Windows**:按 `WIN+R` 並貼上 `%USERPROFILE%\.local\share\opencode`
|
||||
- **macOS/Linux**: `~/.local/share/opencode/`
|
||||
- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.local\share\opencode`
|
||||
|
||||
該目錄包含:
|
||||
|
||||
- `auth.json` - 身分驗證數據,例如 API 金鑰、OAuth 令牌
|
||||
- `auth.json` - 身分驗證資料,如 API 金鑰、OAuth Token
|
||||
- `log/` - 應用程式日誌
|
||||
- `project/` - 專案特定數據,例如工作階段和訊息數據
|
||||
- 如果專案位於 Git 儲存庫中,則它儲存在 `./<project-slug>/storage/` 中
|
||||
- 如果不是 Git 儲存庫,則儲存在 `./global/storage/` 中
|
||||
- `project/` - 專案特定資料,如工作階段和訊息資料
|
||||
- 如果專案位於 Git 儲存庫中,則儲存在 `./<project-slug>/storage/`
|
||||
- 如果不是 Git 儲存庫,則儲存在 `./global/storage/`
|
||||
|
||||
---
|
||||
|
||||
## 桌面應用程式
|
||||
|
||||
opencode Desktop 在背景執行本地 opencode 伺服器(`opencode-cli` sidecar)。大多數問題是由行為不當的外掛、損壞的快取或錯誤的伺服器設定引起的。
|
||||
OpenCode Desktop 會在背景執行一個本地 OpenCode 伺服器(即 `opencode-cli` 附屬程序)。大多數問題是由外掛異常、快取損壞或錯誤的伺服器設定引起的。
|
||||
|
||||
### 快速檢查
|
||||
|
||||
- 完全退出並重新啟動應用程式。
|
||||
- 如果應用程式顯示錯誤螢幕,請單擊「**重新啟動**」並複製錯誤詳細資訊。
|
||||
- 僅限 macOS:`OpenCode` 選單 -> **重新載入 Webview**(如果 UI 為空白/凍結,則有幫助)。
|
||||
- 如果應用程式顯示錯誤頁面,請點擊**重新啟動**並複製錯誤詳情。
|
||||
- 僅限 macOS:`OpenCode` 選單 -> **Reload Webview**(當 UI 空白或凍結時有效)。
|
||||
|
||||
---
|
||||
|
||||
### 禁用外掛
|
||||
### 停用外掛
|
||||
|
||||
如果桌面應用程式在啟動時崩潰、卡住或行為異常,請首先禁用外掛。
|
||||
如果桌面應用程式在啟動時當機、卡住或行為異常,請先停用外掛。
|
||||
|
||||
#### 檢查全域配置
|
||||
#### 檢查全域設定
|
||||
|
||||
打開全域設定檔並查找 `plugin` 鍵。
|
||||
開啟你的全域設定檔,查找 `plugin` 鍵。
|
||||
|
||||
- **macOS/Linux**:`~/.config/opencode/opencode.jsonc`(或 `~/.config/opencode/opencode.json`)
|
||||
- **macOS/Linux**(較舊的安裝):`~/.local/share/opencode/opencode.jsonc`
|
||||
- **Windows**:按 `WIN+R` 並貼上 `%USERPROFILE%\.config\opencode\opencode.jsonc`
|
||||
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc`(或 `~/.config/opencode/opencode.json`)
|
||||
- **macOS/Linux**(舊版安裝): `~/.local/share/opencode/opencode.jsonc`
|
||||
- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.config\opencode\opencode.jsonc`
|
||||
|
||||
如果您配置了外掛,請透過刪除鍵或將其設定為空陣列來暫時禁用它們:
|
||||
如果你設定了外掛,請透過移除該鍵或將其設定為空陣列來暫時停用它們:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
@@ -72,114 +72,114 @@ opencode Desktop 在背景執行本地 opencode 伺服器(`opencode-cli` sidec
|
||||
|
||||
#### 檢查外掛目錄
|
||||
|
||||
opencode 還可以從磁碟載入本地外掛。暫時將它們移開(或重命名資料夾)並重新啟動桌面應用程式:
|
||||
OpenCode 還可以從磁碟載入本地外掛。暫時將這些外掛移走(或重新命名資料夾),然後重新啟動桌面應用程式:
|
||||
|
||||
- **全域外掛**
|
||||
- **macOS/Linux**:`~/.config/opencode/plugins/`
|
||||
- **Windows**:按 `WIN+R` 並貼上 `%USERPROFILE%\.config\opencode\plugins`
|
||||
- **專案外掛**(僅當您使用每個專案配置時)
|
||||
- **macOS/Linux**: `~/.config/opencode/plugins/`
|
||||
- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.config\opencode\plugins`
|
||||
- **專案外掛**(僅當你使用了專案級設定時)
|
||||
- `<your-project>/.opencode/plugins/`
|
||||
|
||||
如果應用程式再次開始工作,請一次重新啟用一個外掛,以找出導致問題的外掛。
|
||||
如果應用程式恢復正常,請逐個重新啟用外掛,找出導致問題的那個。
|
||||
|
||||
---
|
||||
|
||||
### 清除快取
|
||||
|
||||
如果禁用外掛沒有幫助(或者外掛安裝被卡住),請清除快取,以便 opencode 可以重建它。
|
||||
如果停用外掛沒有幫助(或外掛安裝卡住了),請清除快取以便 OpenCode 重新建置。
|
||||
|
||||
1. 完全退出 opencode Desktop。
|
||||
1. 完全退出 OpenCode Desktop。
|
||||
2. 刪除快取目錄:
|
||||
|
||||
- **macOS**:Finder -> `Cmd+Shift+G` -> 貼上 `~/.cache/opencode`
|
||||
- **Linux**:刪除 `~/.cache/opencode`(或執行 `rm -rf ~/.cache/opencode`)
|
||||
- **Windows**:按 `WIN+R` 並貼上 `%USERPROFILE%\.cache\opencode`
|
||||
- **macOS**: Finder -> `Cmd+Shift+G` -> 貼上 `~/.cache/opencode`
|
||||
- **Linux**: 刪除 `~/.cache/opencode`(或執行 `rm -rf ~/.cache/opencode`)
|
||||
- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.cache\opencode`
|
||||
|
||||
3. 重新啟動 opencode 桌面。
|
||||
3. 重新啟動 OpenCode Desktop。
|
||||
|
||||
---
|
||||
|
||||
### 修復伺服器連接問題
|
||||
### 修復伺服器連線問題
|
||||
|
||||
opencode Desktop 可以啟動自己的本地伺服器(預設)或連接到您配置的伺服器 URL。
|
||||
OpenCode Desktop 可以啟動自己的本地伺服器(預設行為),也可以連線到你設定的伺服器 URL。
|
||||
|
||||
如果您看到 **「連接失敗」** 對話方塊(或者應用程式永遠無法通過啟動螢幕),請檢查自定義伺服器 URL。
|
||||
如果你看到**「Connection Failed」**對話框(或應用程式始終停留在啟動畫面),請檢查自訂伺服器 URL。
|
||||
|
||||
#### 清除桌面預設伺服器 URL
|
||||
|
||||
在主螢幕中,單擊伺服器名稱(帶有狀態點)以打開伺服器選取器。在「**預設伺服器**」部分中,單擊「**清除**」。
|
||||
在主頁面上,點擊伺服器名稱(帶有狀態指示點)以開啟伺服器選擇器。在**預設伺服器**部分,點擊**清除**。
|
||||
|
||||
#### 從您的配置中刪除 `server.port` / `server.hostname`
|
||||
#### 從設定中移除 `server.port` / `server.hostname`
|
||||
|
||||
如果您的 `opencode.json(c)` 包含 `server` 部分,請將其暫時刪除並重新啟動桌面應用程式。
|
||||
如果你的 `opencode.json(c)` 包含 `server` 部分,請暫時移除該部分並重新啟動桌面應用程式。
|
||||
|
||||
#### 檢查環境變數
|
||||
|
||||
如果您在環境中設定了 `OPENCODE_PORT`,桌面應用程式將嘗試將該連接埠用於本地伺服器。
|
||||
如果你在環境中設定了 `OPENCODE_PORT`,桌面應用程式將嘗試使用該連接埠作為本地伺服器連接埠。
|
||||
|
||||
- 取消設定 `OPENCODE_PORT`(或選擇一個空閒連接埠)並重新啟動。
|
||||
|
||||
---
|
||||
|
||||
### Linux:Wayland / X11 問題
|
||||
### Linux: Wayland / X11 問題
|
||||
|
||||
在 Linux 上,某些 Wayland 設定可能會導致空白視窗或合成器錯誤。
|
||||
在 Linux 上,某些 Wayland 設定可能會導致視窗空白或合成器錯誤。
|
||||
|
||||
- 如果您在 Wayland 上且應用程式空白/崩潰,請嘗試使用 `OC_ALLOW_WAYLAND=1` 啟動。
|
||||
- 如果這讓事情變得更糟,請將其刪除並嘗試在 X11 工作階段下啟動。
|
||||
- 如果你使用 Wayland 且應用程式出現空白或當機,請嘗試使用 `OC_ALLOW_WAYLAND=1` 啟動。
|
||||
- 如果情況變得更糟,請移除該設定並嘗試在 X11 工作階段下啟動。
|
||||
|
||||
---
|
||||
|
||||
### Windows:WebView2 執行時
|
||||
### Windows: WebView2 執行階段
|
||||
|
||||
在 Windows 上,opencode Desktop 需要 Microsoft Edge **WebView2 執行時**。如果應用程式打開為空白視窗或無法啟動,請安裝/更新 WebView2,然後重試。
|
||||
在 Windows 上,OpenCode Desktop 需要 Microsoft Edge **WebView2 Runtime**。如果應用程式開啟後是空白視窗或無法啟動,請安裝或更新 WebView2 後重試。
|
||||
|
||||
---
|
||||
|
||||
### Windows:一般性能問題
|
||||
### Windows: 常見效能問題
|
||||
|
||||
如果您在 Windows 上遇到性能緩慢、檔案存取問題或終端機問題,請嘗試使用 [WSL(適用於 Linux 的 Windows 子系統)](/docs/windows-wsl)。 WSL 提供了一個可以與 opencode 功能更加無縫協作的 Linux 環境。
|
||||
如果你在 Windows 上遇到效能緩慢、檔案存取問題或終端機問題,請嘗試使用 [WSL (Windows Subsystem for Linux)](/docs/windows-wsl)。WSL 提供了一個 Linux 環境,能更好地與 OpenCode 的功能相容。
|
||||
|
||||
---
|
||||
|
||||
### 通知不顯示
|
||||
|
||||
opencode Desktop 僅在以下情況下顯示系統通知:
|
||||
OpenCode Desktop 僅在以下情況下顯示系統通知:
|
||||
|
||||
- 在您的作業系統設定中啟用 opencode 通知,並且
|
||||
- 應用程式視窗未聚焦。
|
||||
- 在作業系統設定中已為 OpenCode 啟用通知,且
|
||||
- 應用程式視窗未處於焦點狀態。
|
||||
|
||||
---
|
||||
|
||||
### 重置桌面應用程式儲存(最後手段)
|
||||
### 重設桌面應用程式儲存(最後手段)
|
||||
|
||||
如果應用程式無法啟動並且您無法從 UI 內部清除設定,請重置桌面應用程式的保存狀態。
|
||||
如果應用程式無法啟動且你無法從 UI 內部清除設定,請重設桌面應用程式的儲存狀態。
|
||||
|
||||
1. 退出 opencode Desktop。
|
||||
2. 查找並刪除這些檔案(它們位於 opencode Desktop 應用程式資料目錄中):
|
||||
1. 退出 OpenCode Desktop。
|
||||
2. 找到並刪除以下檔案(它們位於 OpenCode Desktop 應用程式資料目錄中):
|
||||
|
||||
- `opencode.settings.dat`(桌面預設伺服器 URL)
|
||||
- `opencode.global.dat` 和 `opencode.workspace.*.dat`(UI 狀態,如最近的伺服器/專案)
|
||||
|
||||
快速找到目錄:
|
||||
快速找到該目錄:
|
||||
|
||||
- **macOS**:Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`(然後搜尋上面的檔名)
|
||||
- **Linux**:在 `~/.local/share` 下搜尋上述檔名
|
||||
- **Windows**:按 `WIN+R` -> `%APPDATA%`(然後搜尋上面的檔名)
|
||||
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`(然後搜尋上述檔案名稱)
|
||||
- **Linux**: 在 `~/.local/share` 下搜尋上述檔案名稱
|
||||
- **Windows**: 按 `WIN+R` -> `%APPDATA%`(然後搜尋上述檔案名稱)
|
||||
|
||||
---
|
||||
|
||||
## 尋求幫助
|
||||
## 取得幫助
|
||||
|
||||
如果您遇到 opencode 問題:
|
||||
如果你遇到 OpenCode 的問題:
|
||||
|
||||
1. **在 GitHub 上報告問題**
|
||||
1. **在 GitHub 上回報問題**
|
||||
|
||||
報告錯誤或請求功能的最佳方式是透過我們的 GitHub 儲存庫:
|
||||
回報 Bug 或請求功能的最佳方式是透過我們的 GitHub 儲存庫:
|
||||
|
||||
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
|
||||
|
||||
在建立新問題之前,請搜尋現有問題以查看您的問題是否已被報告。
|
||||
在建立新 Issue 之前,請先搜尋已有的 Issue,看看你的問題是否已被回報。
|
||||
|
||||
2. **加入我們的 Discord**
|
||||
|
||||
@@ -191,35 +191,34 @@ opencode Desktop 僅在以下情況下顯示系統通知:
|
||||
|
||||
## 常見問題
|
||||
|
||||
以下是一些常見問題以及解決方法。
|
||||
以下是一些常見問題及其解決方法。
|
||||
|
||||
---
|
||||
|
||||
### opencode 無法啟動
|
||||
### OpenCode 無法啟動
|
||||
|
||||
1. 檢查日誌中是否有錯誤訊息
|
||||
2. 嘗試使用 `--print-logs` 執行以查看終端機中的輸出
|
||||
3. 確保您擁有最新版本 `opencode upgrade`
|
||||
1. 檢查日誌中的錯誤訊息
|
||||
2. 嘗試使用 `--print-logs` 執行以在終端機中查看輸出
|
||||
3. 使用 `opencode upgrade` 確保你使用的是最新版本
|
||||
|
||||
---
|
||||
|
||||
### 身分驗證問題
|
||||
|
||||
1. 嘗試使用 TUI 中的 `/connect` 指令重新進行身分驗證
|
||||
2. 檢查您的 API 金鑰是否有效
|
||||
3. 確保您的網路允許連接到供應商的 API
|
||||
1. 嘗試在 TUI 中使用 `/connect` 指令重新進行身分驗證
|
||||
2. 檢查你的 API 金鑰是否有效
|
||||
3. 確保你的網路允許連線到供應商的 API
|
||||
|
||||
---
|
||||
|
||||
### 模型不可用
|
||||
|
||||
1. 檢查您是否已通過供應商的身分驗證
|
||||
2. 驗證配置中的模型名稱是否正確
|
||||
1. 檢查你是否已通過供應商的身分驗證
|
||||
2. 驗證設定中的模型名稱是否正確
|
||||
3. 某些模型可能需要特定的存取權限或訂閱
|
||||
|
||||
如果您遇到 `ProviderModelNotFoundError`,您很可能是錯誤的
|
||||
在某處引用模型。
|
||||
模型應該像這樣引用:`<providerId>/<modelId>`
|
||||
如果你遇到 `ProviderModelNotFoundError`,很可能是在某處錯誤地參考了模型。
|
||||
模型應按如下方式參考:`<providerId>/<modelId>`
|
||||
|
||||
範例:
|
||||
|
||||
@@ -227,18 +226,18 @@ opencode Desktop 僅在以下情況下顯示系統通知:
|
||||
- `openrouter/google/gemini-2.5-flash`
|
||||
- `opencode/kimi-k2`
|
||||
|
||||
要了解您可以存取哪些模型,請執行 `opencode models`
|
||||
要查看你有權存取哪些模型,請執行 `opencode models`
|
||||
|
||||
---
|
||||
|
||||
### 供應商初始化錯誤
|
||||
### ProviderInitError
|
||||
|
||||
如果遇到 ProviderInitError,您的配置可能無效或損壞。
|
||||
如果你遇到 ProviderInitError,很可能是設定無效或已損壞。
|
||||
|
||||
要解決這個問題:
|
||||
要解決此問題:
|
||||
|
||||
1. 首先,按照 [供應商指南](/docs/providers) 驗證您的供應商是否已正確設定
|
||||
2. 如果問題仍然存在,請嘗試清除儲存的配置:
|
||||
1. 首先,按照[供應商指南](/docs/providers)驗證你的供應商是否已正確設定
|
||||
2. 如果問題仍然存在,請嘗試清除已儲存的設定:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.local/share/opencode
|
||||
@@ -246,13 +245,13 @@ opencode Desktop 僅在以下情況下顯示系統通知:
|
||||
|
||||
在 Windows 上,按 `WIN+R` 並刪除:`%USERPROFILE%\.local\share\opencode`
|
||||
|
||||
3. 使用 TUI 中的 `/connect` 指令向您的供應商重新進行身分驗證。
|
||||
3. 在 TUI 中使用 `/connect` 指令重新與供應商進行身分驗證。
|
||||
|
||||
---
|
||||
|
||||
### AI_APICallError 和供應商套件問題
|
||||
|
||||
如果您遇到 API 呼叫錯誤,這可能是由於過時的供應商套件造成的。 opencode 根據需要動態安裝供應商套件(OpenAI、Anthropic、Google 等)並將其快取在本地。
|
||||
如果你遇到 API 呼叫錯誤,可能是由於供應商套件過期導致的。OpenCode 會根據需要動態安裝供應商套件(OpenAI、Anthropic、Google 等)並將它們快取到本地。
|
||||
|
||||
要解決供應商套件問題:
|
||||
|
||||
@@ -264,15 +263,15 @@ opencode Desktop 僅在以下情況下顯示系統通知:
|
||||
|
||||
在 Windows 上,按 `WIN+R` 並刪除:`%USERPROFILE%\.cache\opencode`
|
||||
|
||||
2. 重新啟動 opencode 以重新安裝最新的供應商套件
|
||||
2. 重新啟動 OpenCode 以重新安裝最新的供應商套件
|
||||
|
||||
這將強制 opencode 下載最新版本的供應商套件,這通常可以解決模型參數和 API 更改的相容性問題。
|
||||
這將強制 OpenCode 下載最新版本的供應商套件,通常可以解決模型參數和 API 變更帶來的相容性問題。
|
||||
|
||||
---
|
||||
|
||||
### 複製/貼上在 Linux 上不起作用
|
||||
### 在 Linux 上複製/貼上不可用
|
||||
|
||||
Linux 使用者需要安裝以下剪貼簿公用程式之一才能使用複製/貼上功能:
|
||||
Linux 使用者需要安裝以下剪貼簿工具之一,複製/貼上功能才能正常運作:
|
||||
|
||||
**對於 X11 系統:**
|
||||
|
||||
@@ -288,7 +287,7 @@ apt install -y xsel
|
||||
apt install -y wl-clipboard
|
||||
```
|
||||
|
||||
**對於無介面環境:**
|
||||
**對於無頭環境:**
|
||||
|
||||
```bash
|
||||
apt install -y xvfb
|
||||
@@ -297,4 +296,4 @@ Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
|
||||
export DISPLAY=:99.0
|
||||
```
|
||||
|
||||
opencode 將檢測您是否使用 Wayland 並更喜歡 `wl-clipboard`,否則它將嘗試按 `xclip` 和 `xsel` 的順序尋找剪貼簿工具。
|
||||
OpenCode 會偵測你是否正在使用 Wayland 並優先使用 `wl-clipboard`,否則將按以下順序嘗試查找剪貼簿工具:`xclip` 和 `xsel`。
|
||||
|
||||
Reference in New Issue
Block a user