7.0 KiB
技术栈与依赖
**Referenced Files in This Document ** - [package.json](file://package.json) - [vite.config.ts](file://vite.config.ts) - [tsconfig.json](file://tsconfig.json) - [uno.config.ts](file://uno.config.ts) - [src/main.ts](file://src/main.ts) - [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts) - [src/stores/counter.ts](file://src/stores/counter.ts)目录
核心框架：Vue 3
本项目采用 Vue 3 作为核心前端框架，利用其组合式 API（Composition API）实现更灵活、可复用的逻辑组织。在 main.ts 文件中通过 createApp 初始化应用实例，并挂载根组件 App.vue，构成整个应用的入口。
Vue 3 提供了响应式系统、虚拟 DOM 渲染机制以及强大的组件化能力，使得桌面级 Web 应用的开发更加高效和模块化。结合 Vite 的现代构建流程，实现了极快的冷启动和热更新体验。
Section sources
状态管理：Pinia
Pinia 作为 Vue 官方推荐的状态管理库，在本项目中用于集中管理全局状态。通过 defineStore 创建具有命名空间的 store 实例，如 useCounterStore，支持使用 ref 和 computed 构建响应式状态，并导出操作方法以供组件调用。
在 main.ts 中通过 app.use(createPinia()) 注册 Pinia 插件，使所有组件均可通过 useXXXStore() 获取共享状态，避免了传统 Vuex 的冗余配置，提升了开发效率与类型推断准确性。
classDiagram
class useCounterStore {
+count : Ref<number>
+doubleCount : ComputedRef<number>
+increment() : void
}
useCounterStore --> ref : "uses"
useCounterStore --> computed : "uses"
useCounterStore --> defineStore : "created via"
Diagram sources
Section sources
UI 组件库：Naive UI
项目集成 Naive UI 作为 UI 组件解决方案，提供高质量、可定制的 Vue 3 组件集。为优化打包体积并实现按需引入，项目在 src/common/naive-ui/components.ts 中手动创建了一个轻量化的 UI 实例，仅注册所需组件（如 NButton, NCard, NConfigProvider），并通过 create() 方法生成可被 app.use() 注册的插件对象。
此外，项目还通过 discrete-api.ts 导出独立使用的 API（如 message、modal），并在 theme.ts 中扩展默认主题，自定义主色调为 #0070f3，确保视觉风格统一。
classDiagram
class naiveUi {
+components : Array<Component>
}
naiveUi --> NButton : "includes"
naiveUi --> NCard : "includes"
naiveUi --> NConfigProvider : "includes"
naiveUi --> create : "created via"
Diagram sources
Section sources
原子化样式：UnoCSS
UnoCSS 是一个即时（on-the-fly）原子化 CSS 引擎，取代传统的 Tailwind CSS 实现方式。它允许开发者直接在模板中使用类名（如 flex, p-4, text-lg），并在构建时动态生成最小化 CSS，极大提升样式编写效率并减少冗余代码。
项目通过 unocss/vite 插件集成 UnoCSS，并在 uno.config.ts 中启用 transformerVariantGroup 和 transformerDirectives，支持嵌套语法（如 hover:(bg-red-500 text-white)）和 @apply 指令，增强可读性与灵活性。同时，virtual:uno.css 被引入 main.ts，确保样式正确注入。
Section sources
构建工具：Vite
Vite 作为现代前端构建工具，基于 ES 模块原生支持，显著提升了开发服务器的启动速度与热更新性能。项目通过 vite.config.ts 配置核心插件：
@vitejs/plugin-vue：支持.vue单文件组件解析@vitejs/plugin-vue-jsx：支持 JSX/TSX 语法vite-plugin-vue-devtools：集成 Vue DevTools 调试工具unocss/vite：集成 UnoCSS 样式引擎
配置中还设置了路径别名 @ 指向 src 目录，便于模块导入。Vite 的开箱即用特性与 TypeScript、JSX、Sass 等技术无缝集成，构成了高效的开发环境基础。
flowchart TD
A["用户请求 /"] --> B[Vite Dev Server]
B --> C{资源类型}
C --> |HTML| D[index.html]
C --> |.vue 文件| E[Vite 解析 SFC]
E --> F[编译 template/script/style]
F --> G[返回 ES Module]
C --> |TypeScript| H[Vite 实时转译]
H --> I[浏览器执行]
C --> |UnoCSS 类名| J[UnoCSS 动态生成 CSS]
J --> K[注入 style 标签]
I & K --> L[页面渲染完成]
Diagram sources
Section sources
类型安全：TypeScript
TypeScript 在项目中承担关键的角色，提供静态类型检查以预防运行时错误。项目采用分层配置策略，tsconfig.json 通过 references 引入 tsconfig.node.json 和 tsconfig.app.json，分别处理 Node.js 环境与应用代码的类型定义。
.vue 文件的类型支持通过 vue-tsc 实现，替代标准 tsc 进行类型检查，确保模板中的 props、emits 等具备完整类型推断。配合 VSCode 与 Volar 插件，开发者可在编辑器中获得精准的智能提示与错误检测。
Section sources
关键依赖项版本与选择理由
| 依赖包 | 版本范围 | 选择理由 |
|---|---|---|
| vue | ^3.5.18 | 使用最新稳定版 Vue 3，支持 Composition API 与 Fragment |
| pinia | ^3.0.3 | 官方状态管理库，轻量、类型友好、API 简洁 |
| naive-ui | ^2.42.0 | 功能丰富、文档完善、支持 Tree-shaking 的 Vue 3 组件库 |
| unocss | ^66.4.2 | 即时原子化 CSS，性能优于传统方案，支持高度定制 |
| vite | ^7.0.6 | 极速 HMR、原生 ES Modules 支持、生态成熟 |
| typescript | ~5.8.0 | 精确控制 TS 版本，避免意外升级导致兼容问题 |
| vue-tsc | ^3.0.4 | 专为 Vue + TypeScript 设计的类型检查工具，支持 <script setup> 和模板类型校验 |
这些依赖共同构建了一个现代化、高性能、类型安全的前端开发体系，为项目的长期维护与扩展提供了坚实基础。
Section sources