---
url: /doc/guide/desktop.md
---
> **快速上手** - 安装、首次启动、登录、更新与卸载

本章同时适用于 WinUI 3 原版与 Windows 7 兼容版；两者在功能与交互上保持一致，差异集中在安装前提与系统要求，详见 [Windows 7 版本使用说明](./win7.md)。

## 安装

### 安装版

1. 从[下载页面](/download)获取 `ClassSoftwareHub-Setup-win7-dv<版本>.exe`。
2. 双击运行。安装前若检测到应用正在运行，安装程序会先礼貌关闭（`taskkill`），不退再强杀；应用无未保存状态、设置即时落盘，被杀不丢数据。
3. 按向导完成安装，可选创建桌面快捷方式。
4. 安装完成自动拉起应用。

### 便携版

1. 从[下载页面](/download)获取 `ClassSoftwareHub-Portable-win7-dv<版本>.zip`。
2. 解压到任意位置（U 盘亦可）。
3. 双击根目录的 `ClassSoftwareHub.exe` 启动。
4. `app` 文件夹必须与启动器放在一起，单独拿走 exe 无法启动。

::: warning 校验安装包
每个安装包均附带同名 `.md5` 文件，下载后请校验完整性。
:::

## 首次启动

1. 启动后进入欢迎页，展示站点简介与快速入口。
2. **首次启动必须联网**：安装包不自带内容包，软件清单需从 GitHub 仓库同步；未取到时界面显示「尚未获取到内容」并给出重试入口。
3. 同步完成后即可浏览软件、使用工具。

## 登录

桌面端**无账号登录**。所有需要身份的操作（提交软件、回声洞投稿、反馈中心）均为匿名提交，由维护者在后台处理。

## 主要功能

| 功能 | 说明 |
| --- | --- |
| 软件下载 | 与网页端一致的分类浏览、详情查看、下载与校验值；清单跟随网站数据自动更新 |
| 全站搜索 | 一次搜索软件、内置工具与页面 |
| 常用工具浮窗 | 随机摇号、课表计时、秒表计时、全屏时钟等，可拖边缩放，可置顶 |
| 工具侧边栏 | 可自行拼装：把常用工具拖入侧边栏、排序、拖出删除；支持贴靠（左右两边）与自由（四条边）两种模式 |
| 截屏贴图 | 拖拽框选屏幕区域后进入编辑（画笔 / 荧光笔 / 箭头 / 矩形 / 椭圆 / 文字 / 马赛克），支持撤销重做、复制、存盘与钉图 |
| 外观 | 主界面与外部小窗可分别使用浅色 / 深色；背景支持亚克力 / 云母 / 纯色 |
| 自动更新 | 内置双通道更新器（正式版 / 预览版），自动核对版本、下载并校验安装包 |
| 更新日志 | 站内直接查看历史版本说明 |
| 数据容错 | 单条数据异常不影响整站，页面顶部给出明确提示 |

## 数据存储位置

| 内容 | 位置 |
| --- | --- |
| 设置、缓存、内容（数据根目录） | `%LOCALAPPDATA%\ClassSoftwareHub\` |
| 同步下来的软件数据 | `%LOCALAPPDATA%\ClassSoftwareHub\content\` |
| 日志 | `%LOCALAPPDATA%\ClassSoftwareHub\logs\{启动时间}\`，每次启动一个目录 |
| WebView2 用户数据 | `%LOCALAPPDATA%\ClassSoftwareHub\WebView2\` |
| 便携版排障日志 | 便携版目录旁的 `port.log` |

## 更新

1. 在设置页选择更新通道：正式版（stable）或预览版（insider）。
2. 点击「检查更新」。客户端读取**本版本自己的仓库** Release：正式版取非预发布的最新 Release，预览版取预发布及非预发布。
3. 发现新版本后下载安装包，**校验通过后方可安装**。发布包均附带 `.md5` 资产；若发布方未提供任何可用校验值，更新会中止而不执行未校验的安装包。
4. 安装过程为静默安装，许可页会被跳过并视为已接受，升级流程不被打断。
5. 安装版采用「启动器 + `app\` 子目录」两层结构，更新只替换 `app\` 子目录，启动器与桌面快捷方式路径永远有效。

### 回滚

设置页可查看历史版本列表（正式版通道只列正式版，预览版通道同时列出预览版），选择任意版本安装，不回校验版本高低。

### 便携版更新

便携版不会自动替换自己（正在运行的程序无法覆盖自身）。有新版本时，请到发布页下载新的便携包，解压后**替换整个 `app` 文件夹**；存放在 `%LOCALAPPDATA%\ClassSoftwareHub` 的设置不会丢失。

## 卸载

**安装版**：通过「设置 → 应用 → 已安装的应用」或控制面板的卸载项执行。卸载项显示名形如 `ClassSoftwareHub dv<版本> (Windows 7)`。卸载不会删除 `%LOCALAPPDATA%\ClassSoftwareHub` 中的设置、缓存与日志；如需彻底清除，请手动删除该目录。

**便携版**：直接删除解压目录即可。该形态不写注册表。

## 故障排查

| 现象 | 原因 | 处理方式 |
| --- | --- | --- |
| 双击桌面图标无反应，多次点击仍无界面 | 关闭窗口默认是收进托盘，进程未退出；第二个实例被单实例互斥体拦下 | 已修复：第二个实例会通过命名事件唤醒第一个实例并显示主窗口。若仍无反应，查看托盘区（含溢出区）是否有应用图标 |
| 进程留在任务管理器中，托盘菜单「退出」无效 | 工具浮窗等窗口拦截了关闭事件 | 已通过「应用正在退出」全局标记修复；如复现，请在任务管理器结束进程并反馈 |
| 软件列表为空，提示「尚未获取到内容」 | 首次启动未联网，或 GitHub 访问不通 | 连接网络后点击重试；若持续失败，检查网络能否访问 `github.com` |
| 详情页内打开官网无反应 | 未安装 WebView2 运行时 | 安装 WebView2 运行时；Windows 7 上最高仅支持 109.x 版本 |
| 主界面无法显示 | 极少数老显卡 D3D11 与 OpenGL 均不可用 | 以 `--software-render` 参数启动；或使用 `--takeover` 结束异常实例 |
| 界面点不动或托盘无图标 | 走了非预期的系统版本分支 | 便携版目录旁的 `port.log` 与 `%LOCALAPPDATA%\ClassSoftwareHub\logs\` 下的日志可定位；反馈时请附带 |