故障排查

约 1347 字大约 4 分钟

2026-10-19 20:00:00

按「现象 — 原因 — 处理方式」组织。排查前请先获取日志

排查前置：获取日志

形态	日志位置
桌面端	`%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`，改由安装脚本自行结束进程