# 技术栈与依赖

<cite>
**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)
</cite>

## 目录
1. [核心框架：Vue 3](#核心框架vue-3)  
2. [状态管理：Pinia](#状态管理pinia)  
3. [UI 组件库：Naive UI](#ui-组件库naive-ui)  
4. [原子化样式：UnoCSS](#原子化样式unocss)  
5. [构建工具：Vite](#构建工具vite)  
6. [类型安全：TypeScript](#类型安全typescript)  
7. [关键依赖项版本与选择理由](#关键依赖项版本与选择理由)

## 核心框架：Vue 3

本项目采用 Vue 3 作为核心前端框架，利用其组合式 API（Composition API）实现更灵活、可复用的逻辑组织。在 `main.ts` 文件中通过 `createApp` 初始化应用实例，并挂载根组件 `App.vue`，构成整个应用的入口。

Vue 3 提供了响应式系统、虚拟 DOM 渲染机制以及强大的组件化能力，使得桌面级 Web 应用的开发更加高效和模块化。结合 Vite 的现代构建流程，实现了极快的冷启动和热更新体验。

**Section sources**  
- [src/main.ts](file://src/main.ts#L1-L15)

## 状态管理：Pinia

Pinia 作为 Vue 官方推荐的状态管理库，在本项目中用于集中管理全局状态。通过 `defineStore` 创建具有命名空间的 store 实例，如 `useCounterStore`，支持使用 `ref` 和 `computed` 构建响应式状态，并导出操作方法以供组件调用。

在 `main.ts` 中通过 `app.use(createPinia())` 注册 Pinia 插件，使所有组件均可通过 `useXXXStore()` 获取共享状态，避免了传统 Vuex 的冗余配置，提升了开发效率与类型推断准确性。

```mermaid
classDiagram
class useCounterStore {
+count : Ref<number>
+doubleCount : ComputedRef<number>
+increment() : void
}
useCounterStore --> ref : "uses"
useCounterStore --> computed : "uses"
useCounterStore --> defineStore : "created via"
```

**Diagram sources**  
- [src/stores/counter.ts](file://src/stores/counter.ts#L3-L11)

**Section sources**  
- [src/stores/counter.ts](file://src/stores/counter.ts#L1-L13)
- [src/main.ts](file://src/main.ts#L8-L9)

## 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`，确保视觉风格统一。

```mermaid
classDiagram
class naiveUi {
+components : Array<Component>
}
naiveUi --> NButton : "includes"
naiveUi --> NCard : "includes"
naiveUi --> NConfigProvider : "includes"
naiveUi --> create : "created via"
```

**Diagram sources**  
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts#L1-L11)
- [src/common/naive-ui/theme.ts](file://src/common/naive-ui/theme.ts#L2-L14)

**Section sources**  
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts#L1-L11)

## 原子化样式：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**  
- [uno.config.ts](file://uno.config.ts#L1-L10)
- [vite.config.ts](file://vite.config.ts#L15-L16)
- [src/main.ts](file://src/main.ts#L6)

## 构建工具：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 等技术无缝集成，构成了高效的开发环境基础。

```mermaid
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**  
- [vite.config.ts](file://vite.config.ts#L1-L30)

**Section sources**  
- [vite.config.ts](file://vite.config.ts#L1-L30)

## 类型安全：TypeScript

TypeScript 在项目中承担关键的角色，提供静态类型检查以预防运行时错误。项目采用分层配置策略，`tsconfig.json` 通过 `references` 引入 `tsconfig.node.json` 和 `tsconfig.app.json`，分别处理 Node.js 环境与应用代码的类型定义。

`.vue` 文件的类型支持通过 `vue-tsc` 实现，替代标准 `tsc` 进行类型检查，确保模板中的 props、emits 等具备完整类型推断。配合 VSCode 与 Volar 插件，开发者可在编辑器中获得精准的智能提示与错误检测。

**Section sources**  
- [tsconfig.json](file://tsconfig.json#L1-L12)
- [README.md](file://README.md#L12-L15)

## 关键依赖项版本与选择理由

| 依赖包 | 版本范围 | 选择理由 |
|-------|--------|---------|
| 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**  
- [package.json](file://package.json#L1-L43)