Qoder CN 客户端无法启动——闪退、白屏、启动后卡死
第一步：确认环境
| 检查项 | 预期 |
|---|---|
| 操作系统版本 | Windows 10+ / macOS 12+ |
| 架构 | Windows 必须 64 位；macOS Apple Silicon 或 Intel 均可 |
| 磁盘空间 | 至少 500 MB 可用 |
| 安装包来源 | 官方下载，大小正常 |
如果环境不满足，先升级系统或清理空间。
第二步：重启试试
| 尝试 | 说明 |
|---|---|
| 退出所有 Qoder 进程 | 任务管理器（Ctrl + Shift + Esc）里结束所有 Qoder 相关进程 |
| 重启电脑 | 释放被占用的资源 |
| 从安装目录直接启动 | 不通过快捷方式，直接在 C:\Program Files\Qoder\ 或 /Applications/Qoder CN.app 里双击可执行文件 |
第三步：检查是否被安全软件拦截
杀毒软件可能阻止 Qoder 进程启动：
- 暂时关闭杀毒软件；
- 添加 Qoder CN 安装目录到杀毒软件白名单；
- 重新尝试启动。
第四步：清理本地缓存
Qoder 缓存损坏可能导致启动失败：
| 系统 | 缓存目录 |
|---|---|
| Windows | %APPDATA%\Qoder\ 或 %LOCALAPPDATA%\Qoder\ |
| macOS | ~/Library/Application Support/Qoder/ |
备份目录内容后删除，让 Qoder 下次启动时重建。
第五步：卸载重装
前面四步都试过还不行：
- 完全卸载 Qoder CN；
- 去官方下载最新版安装包；
- 安装到默认路径；
- 首次启动时 macOS 点「仍然打开」、Windows 点「仍要运行」。
启动后白屏 / 卡死
启动了但界面一直白屏或卡死不动，通常是：
| 可能原因 | 解决 |
|---|---|
| 网络问题 | 断网重试一次，或切换网络 |
| 首次启动需要初始化 | 等待 1~3 分钟，不卡了就是正常的 |
| 用户数据损坏 | 删除缓存目录（见第四步） |
| Qoder 后台服务没起来 | 任务管理器看有没有 Qoder 相关进程，有就结束后重启 |
日志排查
如果需要定位更精确的原因，查看 Qoder 日志文件：
| 系统 | 日志位置 |
|---|---|
| Windows | %APPDATA%\Qoder\logs\ |
| macOS | ~/Library/Logs/Qoder/ |
找最新的 .log 文件，搜 ERROR 或 FATAL。
还不行
记录以下信息后提交 Feedback 或论坛发帖：
- 操作系统版本（含 Build）；
- Qoder CN 版本号（官方下载页能看到）；
- 启动方式（快捷方式 / 直接双击）；
- 报错截图或日志片段；
- 你已经尝试过的步骤。
下一步
- 启动了但登录不了 → 登录或在线功能异常
- 启动后 Agent 行为异常 → 继续看后面的排查页