161 lines
6.1 KiB
Markdown
161 lines
6.1 KiB
Markdown
# 快速开始
|
||
|
||
<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) |