docs: improve zh-cn and zh-tw documentation translations (#13942)

This commit is contained in:
chenmi
2026-02-17 06:06:39 -06:00
committed by GitHub
parent 8d0a303af4
commit 4fd3141ab5
68 changed files with 4624 additions and 4518 deletions
@@ -1,67 +1,67 @@
---
title: 故障排除
description: 常见问题以及如何解决它们。
description: 常见问题及其解决方法。
---
要排除 opencode 的问题,请首先检查其存储在磁盘上的日志和本地数据。
要调试 OpenCode 的问题,请先检查其存储在磁盘上的日志和本地数据。
---
## 日志
日志文件写入:
日志文件写入位置:
- **macOS/Linux**: `~/.local/share/opencode/log/`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode\log`
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode\log`
日志档案以时间命名(例如`2025-01-09T123456.log`),并保留最近10个日志档案。
日志文件以时间戳命名(例如 `2025-01-09T123456.log`),并保留最近的 10 个日志文件。
You can set the log level with the `--log-level` command-line option to get more detailed debug information. For example, `opencode --log-level DEBUG`.
你可以通过 `--log-level` 命令行选项设置日志级别以获取更详细的调试信息。例如:`opencode --log-level DEBUG`。
---
## 存储
opencode程序将会话数据和其他应用程序数据存储在磁碟上:
OpenCode 将会话数据和其他应用数据存储在磁盘上:
- **macOS/Linux**: `~/.local/share/opencode/`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode`
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode`
该目录包含:
- `auth.json` - 身份验证凭据,例如 API 密钥、OAuth Tokens
- `auth.json` - 身份验证数据,如 API 密钥、OAuth Token
- `log/` - 应用日志
- `project/` - 项目特定数据,例如会话和消息数据
- 如果项目位于 Git 仓库中,则存储在 `./<project-slug>/storage/` 中
- 如果不是 Git 存储库,则存储在 `./global/storage/` 中
- `project/` - 项目特定数据,如会话和消息数据
- 如果项目位于 Git 仓库中,则存储在 `./<project-slug>/storage/`
- 如果不是 Git 仓库,则存储在 `./global/storage/`
---
## 桌面应用程序
## 桌面应用
opencode Desktop runs a local opencode server (the `opencode-cli` sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
OpenCode Desktop 会在后台运行一个本地 OpenCode 服务器(即 `opencode-cli` 附属进程)。大多数问题是由插件异常、缓存损坏或错误的服务器设置引起的。
### 快速检查
- 完全退出并重新启动应用程序。
- 如果应用程序显示错误界面,请单击“**重新启动**”并复制错误详细信息。
- macOS only: `OpenCode` menu -> **Reload Webview** (helps if the UI is blank/frozen).
- 完全退出并重新启动应用。
- 如果应用显示错误页面,请点击**重新启动**并复制错误详情。
- 仅限 macOS:`OpenCode` 菜单 -> **Reload Webview**(当 UI 空白或冻结时有效)。
---
### 禁用插件
如果桌面应用程序在启动时崩溃、挂起或行为异常,请首先禁用插件。
如果桌面应用在启动时崩溃、卡住或行为异常,请先禁用插件。
#### 检查全域性配置
#### 检查全局配置
开启全域性文件并查询`plugin`键。
打开你的全局配置文件,查找 `plugin` 键。
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (or `~/.config/opencode/opencode.json`)
- **macOS/Linux** (older installs): `~/.local/share/opencode/opencode.jsonc`
- **Windows**: Press `WIN+R` and paste `%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,118 +72,118 @@ opencode Desktop runs a local opencode server (the `opencode-cli` sidecar) in th
#### 检查插件目录
opencode 还可以从磁碟加载本地外挂。暂时将它们移开(或重新命名资料夹)并重新启动桌面应用程序:
OpenCode 还可以从磁盘加载本地插件。临时将这些插件移走(或重命名文件夹),然后重新启动桌面应用:
- **全域性插件**
- **全局插件**
- **macOS/Linux**: `~/.config/opencode/plugins/`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\plugins`
- **项目插件**(仅当您使用每个项目配置时)
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.config\opencode\plugins`
- **项目插件**(仅当你使用了项目级配置时)
- `<your-project>/.opencode/plugins/`
如果应用程序再次开始工作,请一次重新启用一个插件,以找出导致问题的插件。
如果应用恢复正常,请逐个重新启用插件,找出导致问题的那个。
---
### 清除缓存
如果取消外挂没有帮助(或者外挂安装被卡住),请清除缓存,方便opencode可以重建它。
如果禁用插件没有帮助(或插件安装卡住了),请清除缓存以便 OpenCode 重新构建。
1. 完全退出 opencode 桌面。
1. 完全退出 OpenCode Desktop。
2. 删除缓存目录:
- **macOS**: Finder -> `Cmd+Shift+G` -> paste `~/.cache/opencode`
- **Linux**: delete `~/.cache/opencode` (or run `rm -rf ~/.cache/opencode`)
- **Windows**: Press `WIN+R` and paste `%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
#### 清除桌面默认服务器 URL
在主屏幕中,单击服务器名称(带有状态点)以打开服务器选择器。在“**默认服务器**”部分中,单击“**清除**”。
在主页面上,点击服务器名称(带有状态指示点)以打开服务器选择器。在**默认服务器**部分,点击**清除**。
#### 从配置中删除 `server.port` / `server.hostname`
#### 从配置中移除 `server.port` / `server.hostname`
If your `opencode.json(c)` contains a `server` section, temporarily remove it and restart the desktop app.
如果你的 `opencode.json(c)` 包含 `server` 部分,请临时移除该部分并重新启动桌面应用。
#### 检查环境变量
如果您在环境中设置了 `OPENCODE_PORT`,桌面应用程序将尝试将交换机用于本地服务器。
如果你在环境中设置了 `OPENCODE_PORT`,桌面应用将尝试使用该端口作为本地服务器端口。
- 取消设置`OPENCODE_PORT`(或选择一个休闲摊)并重新启动。
- 取消设置 `OPENCODE_PORT`(或选择一个空闲端口)并重新启动。
---
### Linux:Wayland / X11 问题
### Linux: Wayland / X11 问题
在 Linux 上,某些 Wayland 设置可能会导致空白视窗或合成器错误。
在 Linux 上,某些 Wayland 设置可能会导致窗口空白或合成器错误。
- 如果您在 Wayland 程序上并且应用的是 blank/crashing,请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
- 如果这让事情变得更糟糕,请完成其删除并尝试在 X11 会话下启动。
- 如果你使用 Wayland 且应用出现空白或崩溃,请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
- 如果情况变得更糟,请移除该设置并尝试在 X11 会话下启动。
---
### Windows:WebView2执行时
### Windows: WebView2 运行时
在 Windows 上,opencode 桌面需要 Microsoft Edge **WebView2 执行时**。如果应用程序打开为空白视窗或无法启动,请 install/update WebView2 并重试。
在 Windows 上,OpenCode Desktop 需要 Microsoft Edge **WebView2 Runtime**。如果应用打开后是空白窗口或无法启动,请安装或更新 WebView2 后重试。
---
### Windows:一般问题
### Windows: 常见性能问题
If you're experiencing slow performance, file access issues, or terminal problems on Windows, try using [WSL (Windows Subsystem for Linux)](/docs/windows-wsl). WSL provides a Linux environment that works more seamlessly with opencode's features.
如果你在 Windows 上遇到性能缓慢、文件访问问题或终端问题,请尝试使用 [WSL (Windows Subsystem for Linux)](/docs/windows-wsl)。WSL 提供了一个 Linux 环境,能更好地与 OpenCode 的功能兼容。
---
### 通知不显示
opencode 桌面仅在以下情况下显示系统通知:
OpenCode Desktop 仅在以下情况下显示系统通知:
- 在您的作业系统中设置为 opencode 启用了通知,并且
- 应用程序视窗未聚焦。
- 在操作系统设置中已为 OpenCode 启用通知,且
- 应用窗口未处于焦点状态。
---
### 重置桌面应用程序储存(最后的手段)
### 重置桌面应用存储(最后手段)
如果应用程序无法并且启动您无法从 UI 内部清除设置,请重置桌面应用程序的存储状态。
如果应用无法启动且你无法从 UI 内部清除设置,请重置桌面应用的保存状态。
1. 退出 opencode 桌面。
2. 查询并删除这些文件(它们位于 opencode 桌面应用程序数据目录中):
1. 退出 OpenCode Desktop。
2. 找到并删除以下文件(它们位于 OpenCode Desktop 应用数据目录中):
- `opencode.settings.dat` (desktop default server URL)
- `opencode.global.dat` and `opencode.workspace.*.dat` (UI state like recent servers/projects)
- `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. **加入我们的不和谐**
2. **加入我们的 Discord**
获得实时帮助和社群讨论,请加入我们的Discord服务器:
如需实时帮助和社区讨论,请加入我们的 Discord 服务器:
[**opencode.ai/discord**](https://opencode.ai/discord)
@@ -191,35 +191,34 @@ opencode 桌面仅在以下情况下显示系统通知:
## 常见问题
以下是一些常见问题以及解决方法。
以下是一些常见问题及其解决方法。
---
### opencode 无法启动
### OpenCode 无法启动
1. 检查日志中是否有错误消息
2. 尝试使用 `--print-logs` 执行以查看终端中的输出
3. Ensure you have the latest version with `opencode upgrade`
1. 检查日志中的错误消息
2. 尝试使用 `--print-logs` 运行以在终端中查看输出
3. 使用 `opencode upgrade` 确保你使用的是最新版本
---
### 身份验证问题
1. 尝试使用 TUI 中的 `/connect` 命令重新进行身份验证
2. 检查您的API 密钥是否有效
3. 保证您的网路允许连线到达辉煌的API
1. 尝试在 TUI 中使用 `/connect` 命令重新进行身份验证
2. 检查你的 API 密钥是否有效
3. 确保你的网络允许连接到提供商的 API
---
### 模型不可用
1. 检查您是否已通过提供商的身份验证
1. 检查你是否已通过提供商的身份验证
2. 验证配置中的模型名称是否正确
3. 某些模型可能需要特定的访问权限或订阅
如果您遇到 `ProviderModelNotFoundError` 您很可能是错误的
在某处引用模型。
模型应该像这样引用:`<providerId>/<modelId>`
如果你遇到 `ProviderModelNotFoundError`,很可能是在某处错误地引用了模型。
模型应按如下方式引用:`<providerId>/<modelId>`
示例:
@@ -227,54 +226,54 @@ opencode 桌面仅在以下情况下显示系统通知:
- `openrouter/google/gemini-2.5-flash`
- `opencode/kimi-k2`
To figure out what models you have access to, run `opencode models`
要查看你有权访问哪些模型,请运行 `opencode models`
---
### 提供商初始化错误
### ProviderInitError
如果遇到 ProviderInitError,您的配置可能无效或损坏。
如果你遇到 ProviderInitError,很可能是配置无效或已损坏。
要解决这个问题:
要解决此问题:
1. 首先,按照[提供商指南](/docs/providers) 验证您的事业是否已正确设置
2. 如果问题仍然存在,请尝试清除储存的配置:
1. 首先,按照[提供商指南](/docs/providers)验证你的提供商是否已正确设置
2. 如果问题仍然存在,请尝试清除已存储的配置:
```bash
rm -rf ~/.local/share/opencode
```
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.local\share\opencode`
在 Windows 上,按 `WIN+R` 并删除:`%USERPROFILE%\.local\share\opencode`
3. 使用 TUI 中的 `/connect` 命令指示您的企业重新进行身份验证。
3. 在 TUI 中使用 `/connect` 命令重新与提供商进行身份验证。
---
### AI_API_CallError 和提供包问题
### AI_APICallError 和提供商包问题
如果您遇到 API 呼叫错误,这可能是由于过去提供包造成的。 opencode 根据需要动态安装提供包(OpenAI、Anthropic、Google 等)将其缓存放在本地。
如果你遇到 API 调用错误,可能是由于提供商包过期导致的。OpenCode 会根据需要动态安装提供商包(OpenAI、Anthropic、Google 等)并将它们缓存到本地。
要解决provider 包问题:
要解决提供商包问题:
1. 清除provider 包缓存:
1. 清除提供商包缓存:
```bash
rm -rf ~/.cache/opencode
```
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`
在 Windows 上,按 `WIN+R` 并删除:`%USERPROFILE%\.cache\opencode`
2. 重新启动 opencode 以重新安装最新的提供包
2. 重新启动 OpenCode 以重新安装最新的提供商包
这将需要 opencode 下载最新版本的提供包,这通常可以解决模型参数和 API 更改的兼容性问题。
这将强制 OpenCode 下载最新版本的提供商包,通常可以解决模型参数和 API 变更带来的兼容性问题。
---
### 复制/粘贴在 Linux 上不可用
### 在 Linux 上复制/粘贴不可用
Linux 用户需要安装以下剪贴簿实用程序之一才能使 copy/paste 功能正常工作:
Linux 用户需要安装以下剪贴板工具之一,复制/粘贴功能才能正常工作:
**对于X11系统:**
**对于 X11 系统:**
```bash
apt install -y xclip
@@ -282,7 +281,7 @@ apt install -y xclip
apt install -y xsel
```
** 对于 Wayland 系统:**
**对于 Wayland 系统:**
```bash
apt install -y wl-clipboard
@@ -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`。