---
url: /doc/guide/troubleshooting.md
---
> 按「现象 — 原因 — 处理方式」组织。排查前请先获取日志

## 排查前置：获取日志

| 形态 | 日志位置 |
| --- | --- |
| 桌面端 | `%LOCALAPPDATA%\ClassSoftwareHub\logs\{启动时间}\`，每次启动一个目录 |
| 桌面端（便携版） | 便携版目录旁的 `port.log` |
| 桌面端（崩溃） | 上述目录中的 `crash.log` |

日志行格式为 `[时间] [级别] [模块] 消息`。反馈问题时请附带 `crash.log` 与最近的 `app.log`。

**诊断控制台**：正式版产物为 Windows 子系统，双击不弹出控制台。如需在现场看到 stdout/stderr，可使用带 `-p:CshConsoleBuild=true` 的专用构建（该开关仅用于现场排障，产物不进发布包）。

**分支模拟**：在开发机上可加 `--simulate-win7` 参数（或设环境变量 `CSH_SIMULATE_WIN7=1`）强制走 Windows 7 判定分支，无需真装一台 Windows 7 即可复现教室机的代码路径。注意这只是分支模拟，机器真实内核仍是开发机系统，个别 API 的实际行为会有差异。

## 命令行开关

| 开关 | 作用 | 适用场景 |
| --- | --- | --- |
| `--software-render` | 强制软件渲染 | 老显卡 D3D11 与 OpenGL 均不可用，界面不出或花屏 |
| `--gpu-render` | 放行 GPU 渲染降级链 | 在 Windows 7 上对比验证 GPU 路径 |
| `--takeover` | 单实例冲突时跳过敲门等待，直接结束拿不出可见主窗口的现有实例 | 看不到界面又不想开任务管理器 |
| `--simulate-win7` | 强制按 Windows 7 分支运行 | 开发机复现教室机代码路径 |

上述开关正式版同样识别，现场排障时无需专门换包。

## 现象与处理

### 启动类

| 现象 | 原因 | 处理方式 |
| --- | --- | --- |
| 双击无任何反应 | 单实例互斥体拦下第二个实例，而第一个实例拿不出可见主窗口 | 加 `--takeover` 启动一次 |
| 启动后 6 秒以上才出界面 | .NET 运行时加载与 JIT 开销 | 属预期。发布产物已启用 ReadyToRun 预编译；老机器上如需进一步缩短，可关闭不必要的开机启动项 |
| 启动即崩溃，`crash.log` 有记录 | 运行时或依赖异常 | 查看 `crash.log` 中的异常类型与堆栈，附带反馈 |

### 渲染类

| 现象 | 原因 | 处理方式 |
| --- | --- | --- |
| 界面花屏或不出 | 显卡驱动不兼容 D3D11 / OpenGL | 加 `--software-render` 启动 |
| 随机灰矩形残影 | Windows 7 老显卡表面保帧不可靠 | Windows 7 默认已走软件渲染；如仍出现，显式加 `--software-render` |
| 背景透明异常（出现黑块或穿透） | DWM 合成被关闭（经典 / 基本主题） | 改用启用 Aero 的主题；程序在合成关闭时会自动退回纯色底 |
| 圆角、云母、亚克力缺失 | Windows 7 不支持这些特性 | 属预期降级，非故障 |

### 数据类

| 现象 | 原因 | 处理方式 |
| --- | --- | --- |
| 软件列表为空 | 未联网或 GitHub 访问不通 | 联网后重试；检查能否访问 `github.com` |
| 软件列表部分缺失 | 个别 JSON 格式错误被跳过 | 页面顶部会给出提示条，列出失败文件与原因 |
| 数据一直不更新 | 内容同步失败 | 查看日志中 `content` 模块的链路记录，其中会记录每一步的结果与耗时 |
| 图标加载缓慢 | 图标托管在 GitHub / jsDelivr 等国内不稳定域名 | 维护者可执行 `python scripts/icon-sync.py --apply` 生成本地副本 |

### 更新类

| 现象 | 原因 | 处理方式 |
| --- | --- | --- |
| 检查更新提示「尚未配置更新源」 | 更新仓库常量未配置 | 检查 `src/Core/ShellConfig.cs` 的 `UpdateRepoOwner` / `UpdateRepoName` |
| 更新下载后校验失败 | 下载包不完整或被篡改 | 重新下载；若持续失败，请反馈该版本的 `.md5` 与实际哈希 |
| 更新中止且提示缺少校验值 | 发布方未提供任何可用校验值 | 属预期的安全中止，不会执行未校验的安装包。请发布方补传 `.md5` 资产 |
| 收不到预览版更新 | 当前处于正式版通道 | 在设置页切换到预览版（insider）通道 |
| 收到了另一个版本的更新 | 更新仓库配置指向了共享仓库 | 确认 `UpdateRepoName` 指向本版本自己的仓库 |

### 安装类

| 现象 | 原因 | 处理方式 |
| --- | --- | --- |
| 安装程序提示系统不满足要求 | 低于 Windows 7 SP1 | 安装 Windows 7 Service Pack 1，或改用网页版 |
| 安装过程中提示应用正在运行 | 旧版本进程未退出（关闭窗口默认收进托盘） | 按提示确认，安装程序会先礼貌关闭，不退再强杀 |
| 安装后桌面没有快捷方式 | 安装时取消了「创建桌面快捷方式」任务 | 重新运行安装程序并勾选该任务；升级时会按桌面现状保留，不会强行建回 |
| 静默更新「什么都没发生」 | 旧版安装脚本曾依赖 `AppMutex` 拦运行中实例，弹框被 `/SUPPRESSMSGBOXES` 自动取消 | 已移除 `AppMutex`，改由安装脚本自行结束进程 |

## 反馈问题时请提供

1. 操作系统版本（例如 Windows 7 SP1 64 位，Build 7601）。
2. 应用版本（设置页「关于」中查看）。
3. 安装形态（安装版 / 便携版）与更新通道（正式版 / 预览版）。
4. `crash.log`，必要时附上最近的 `app.log`。
5. 复现步骤与截图。
6. 便携版请附带 `port.log`。