# 快速开始

<cite>
**本文档中引用的文件**  
- [README.md](file://README.md)
- [package.json](file://package.json)
- [vite.config.ts](file://vite.config.ts)
- [main.ts](file://src/main.ts)
- [index.html](file://index.html)
- [tsconfig.app.json](file://tsconfig.app.json)
- [tsconfig.json](file://tsconfig.json)
- [tsconfig.node.json](file://tsconfig.node.json)
- [env.d.ts](file://env.d.ts)
</cite>

## 目录
1. [简介](#简介)
2. [开发环境准备](#开发环境准备)
3. [项目初始化与依赖安装](#项目初始化与依赖安装)
4. [启动开发服务器](#启动开发服务器)
5. [构建生产版本](#构建生产版本)
6. [package.json 脚本命令详解](#packagejson-脚本命令详解)
7. [常见问题排查](#常见问题排查)
8. [首次运行效果验证](#首次运行效果验证)

## 简介

`vue-desktop` 是一个基于 Vue 3 和 Vite 构建的桌面风格前端项目，模拟操作系统桌面界面，支持图标布局、窗口管理等功能。本指南旨在帮助开发者快速在本地搭建开发环境，完成依赖安装、服务启动和构建发布等核心操作，并提供新手友好的故障排查建议。

**Section sources**
- [README.md](file://README.md#L0-L37)

## 开发环境准备

在开始之前，请确保您的开发机器满足以下最低要求：

- **浏览器支持**：Chrome 84+、Edge 84+、Firefox 79+、Safari 14+
- **Node.js 版本**：根据 `package.json` 中的 `engines` 字段，推荐使用 Node.js v20.19.0 或更高版本（v22.12.0 及以上），不支持 IE 浏览器。
- **包管理工具**：项目使用 `pnpm` 进行依赖管理，需提前安装 pnpm。

推荐开发环境为 VSCode 配合 Volar 插件，以获得最佳的 `.vue` 文件类型支持和开发体验。

**Section sources**
- [package.json](file://package.json#L5-L7)
- [README.md](file://README.md#L0-L6)

## 项目初始化与依赖安装

进入项目根目录后，执行以下命令安装项目所需的所有依赖：

```bash
pnpm install
```

该命令将根据 `package.json` 和 `pnpm-lock.yaml` 安装所有生产与开发依赖，包括 Vue 3、Pinia、Naive UI、Vite、TypeScript 等核心库。

安装完成后，您可以在 `node_modules/` 目录下看到所有已安装的依赖包。

**Section sources**
- [README.md](file://README.md#L30-L31)
- [package.json](file://package.json#L10-L41)

## 启动开发服务器

安装完成后，可通过以下命令启动本地开发服务器：

```bash
pnpm dev
```

此命令实际执行的是 `vite` 命令，启动基于 Vite 的开发服务器，具备热更新（HMR）功能，修改代码后浏览器会自动刷新。

默认情况下，开发服务器将在 `http://localhost:5173` 启动。打开浏览器访问该地址即可查看应用界面。

**Section sources**
- [README.md](file://README.md#L33-L34)
- [package.json](file://package.json#L12)
- [vite.config.ts](file://vite.config.ts#L0-L29)

## 构建生产版本

当需要发布应用时，运行以下命令进行生产环境构建：

```bash
pnpm build
```

该命令会依次执行：
1. `type-check`：使用 `vue-tsc` 对项目进行类型检查
2. `build-only`：调用 `vite build` 编译并压缩代码，输出至 `dist/` 目录

构建完成后，`dist/` 文件夹将包含所有静态资源，可部署到任意静态服务器。

**Section sources**
- [README.md](file://README.md#L35-L37)
- [package.json](file://package.json#L13-L15)

## package.json 脚本命令详解

以下是 `package.json` 中定义的主要脚本及其作用：

| 脚本名称 | 命令内容 | 功能说明 |
|---------|--------|--------|
| `dev` | `vite` | 启动 Vite 开发服务器，支持热重载 |
| `build` | `run-p type-check "build-only {@}" --` | 并行执行类型检查和构建任务 |
| `preview` | `vite preview` | 在本地预览 `dist/` 目录中的生产构建结果 |
| `build-only` | `vite build` | 仅执行构建，不进行类型检查 |
| `type-check` | `vue-tsc --build` | 使用 `vue-tsc` 对 `.vue` 文件进行类型检查 |
| `format` | `prettier --write src/` | 使用 Prettier 格式化 `src/` 目录下的代码 |

这些脚本通过 `npm-run-all2` 实现并发执行（如 `run-p`），提升构建效率。

**Section sources**
- [package.json](file://package.json#L11-L20)

## 常见问题排查

### Node.js 版本不兼容

如果运行 `pnpm install` 时报错提示 Node.js 版本不符合要求，请检查当前版本：

```bash
node -v
```

确保版本符合 `^20.19.0 || >=22.12.0` 范围。建议使用 [nvm](https://github.com/nvm-sh/nvm) 管理多个 Node.js 版本。

### 依赖安装失败

若 `pnpm install` 失败，尝试以下步骤：
1. 清除缓存：`pnpm store prune`
2. 检查网络，必要时配置镜像源
3. 删除 `node_modules` 和 `pnpm-lock.yaml` 后重新安装

### 类型检查错误

运行 `pnpm type-check` 时可能出现类型错误，通常是由于 `.vue` 文件的 TypeScript 类型未被正确识别。确保已安装 Volar 插件并禁用 Vetur。

### 构建失败

构建失败可能由语法错误或路径别名问题引起。检查 `vite.config.ts` 中的 `@` 别名配置是否正确指向 `src/` 目录。

**Section sources**
- [package.json](file://package.json#L5-L7)
- [vite.config.ts](file://vite.config.ts#L18-L22)
- [tsconfig.app.json](file://tsconfig.app.json#L0-L24)
- [env.d.ts](file://env.d.ts#L0-L1)

## 首次运行效果验证

成功运行 `pnpm dev` 并在浏览器中打开 `http://localhost:5173` 后，您应看到一个类桌面风格的界面，包含网格布局的应用图标容器。页面标题为“vue-desktop”，DOM 结构中 `<div id="app">` 已被 Vue 应用挂载。

主组件 `App.vue` 通过 `main.ts` 初始化，使用了 Pinia 状态管理和 Naive UI 组件库。界面响应式适配窗口大小变化，图标按网格自动排列。

若能看到图标容器且无控制台报错，则表示环境搭建成功。

**Section sources**
- [index.html](file://index.html#L0-L13)
- [main.ts](file://src/main.ts#L0-L15)
- [src/ui/desktop-container/DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L0-L22)
- [src/ui/desktop-container/useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L0-L37)