6.1 KiB
快速开始
**本文档中引用的文件** - [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)目录
简介
vue-desktop 是一个基于 Vue 3 和 Vite 构建的桌面风格前端项目，模拟操作系统桌面界面，支持图标布局、窗口管理等功能。本指南旨在帮助开发者快速在本地搭建开发环境，完成依赖安装、服务启动和构建发布等核心操作，并提供新手友好的故障排查建议。
Section sources
开发环境准备
在开始之前，请确保您的开发机器满足以下最低要求：
- 浏览器支持：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
项目初始化与依赖安装
进入项目根目录后，执行以下命令安装项目所需的所有依赖：
pnpm install
该命令将根据 package.json 和 pnpm-lock.yaml 安装所有生产与开发依赖，包括 Vue 3、Pinia、Naive UI、Vite、TypeScript 等核心库。
安装完成后，您可以在 node_modules/ 目录下看到所有已安装的依赖包。
Section sources
启动开发服务器
安装完成后，可通过以下命令启动本地开发服务器：
pnpm dev
此命令实际执行的是 vite 命令，启动基于 Vite 的开发服务器，具备热更新（HMR）功能，修改代码后浏览器会自动刷新。
默认情况下，开发服务器将在 http://localhost:5173 启动。打开浏览器访问该地址即可查看应用界面。
Section sources
构建生产版本
当需要发布应用时，运行以下命令进行生产环境构建：
pnpm build
该命令会依次执行：
type-check：使用vue-tsc对项目进行类型检查build-only：调用vite build编译并压缩代码，输出至dist/目录
构建完成后，dist/ 文件夹将包含所有静态资源，可部署到任意静态服务器。
Section sources
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
常见问题排查
Node.js 版本不兼容
如果运行 pnpm install 时报错提示 Node.js 版本不符合要求，请检查当前版本：
node -v
确保版本符合 ^20.19.0 || >=22.12.0 范围。建议使用 nvm 管理多个 Node.js 版本。
依赖安装失败
若 pnpm install 失败，尝试以下步骤：
- 清除缓存：
pnpm store prune - 检查网络，必要时配置镜像源
- 删除
node_modules和pnpm-lock.yaml后重新安装
类型检查错误
运行 pnpm type-check 时可能出现类型错误，通常是由于 .vue 文件的 TypeScript 类型未被正确识别。确保已安装 Volar 插件并禁用 Vetur。
构建失败
构建失败可能由语法错误或路径别名问题引起。检查 vite.config.ts 中的 @ 别名配置是否正确指向 src/ 目录。
Section sources
首次运行效果验证
成功运行 pnpm dev 并在浏览器中打开 http://localhost:5173 后，您应看到一个类桌面风格的界面，包含网格布局的应用图标容器。页面标题为“vue-desktop”，DOM 结构中 <div id="app"> 已被 Vue 应用挂载。
主组件 App.vue 通过 main.ts 初始化，使用了 Pinia 状态管理和 Naive UI 组件库。界面响应式适配窗口大小变化，图标按网格自动排列。
若能看到图标容器且无控制台报错，则表示环境搭建成功。
Section sources