技术栈与工程规范

本章不只列出依赖名称，还说明每项技术在项目中的职责、常见修改入口和升级时需要关注的边界。版本信息以当前 package.json 为准。

运行环境

工具	最低版本	说明
Node.js	20.19.0	由 package.json#engines 约束
pnpm	8.8.0	项目使用 pnpm-lock.yaml 管理依赖
浏览器	现代浏览器	生产构建目标为 es2020

建议团队统一 Node.js 与 pnpm 版本，不要在同一仓库混用 npm、Yarn 和 pnpm 生成多份锁文件。

核心技术

分类	技术	在项目中的职责
应用框架	Vue 3.5	组合式 API、单文件组件和响应式状态
开发语言	TypeScript 5.6	页面、路由、接口和组件类型约束
构建工具	Vite 8	开发服务、环境变量、代理、分包与生产构建
路由	Vue Router 4.5	Hash 路由、守卫、动态注册和页面导航
状态管理	Pinia 3	用户、菜单、设置、标签页和业务状态
状态持久化	pinia-plugin-persistedstate	按 Store 保存用户偏好与 Access Token
UI 组件	Element Plus 2.11	表单、表格、弹窗和基础交互控件
原子样式	Tailwind CSS 4	布局工具类与项目主题变量映射
样式预处理	Sass	Element Plus 主题和项目 SCSS
HTTP	Axios 1.19	统一请求、Token、响应解包和错误处理
国际化	vue-i18n 9.14	中英文界面与页面标题

业务与可视化依赖

项目按业务需要集成了：

• ECharts 6：仪表盘、数据大屏和统计图表。
• Vue Flow：工作流画布和节点交互。
• WangEditor：富文本编辑。
• XGPlayer：视频播放。
• SheetJS：Excel 读取和导出。
• Iconify：业务图标。
• DOMPurify：动态 HTML 净化。
• VueUse：常用浏览器与响应式组合能力。

这些依赖不会全部进入首屏。build/vite/chunks.ts 会按框架、Element Plus 功能域、图表、编辑器、图标和办公媒体拆分 Chunk；非首屏 CSS 和部分模块预加载也会被延后。

Vite 工程能力

关键配置位于：

vite.config.ts
build/vite/plugins.ts
build/vite/chunks.ts
build/vite/css.ts
build/vite/optimize-deps.ts

当前已经配置：

• @、@views、@imgs、@icons、@utils、@stores、@styles 路径别名。
• Vue、Vue Router、Pinia 和 VueUse API 自动导入。
• src/components 与 Element Plus 组件自动注册。
• Tailwind CSS v4 Vite 插件。
• 开发环境 Vue DevTools。
• 生产环境 Gzip 压缩和 Oxc 压缩。
• version.json 构建版本文件。
• /api 与 /uploads 开发代理。

自动导入不等于全局魔法

开发环境会生成自动导入类型声明。新增依赖或修改自动导入配置后，如果编辑器类型没有更新，重新运行 pnpm dev，并检查 build/vite/plugins.ts，不要在业务代码中重复维护第二套自动导入配置。

代码质量工具

命令	作用
pnpm lint	执行 ESLint 检查
pnpm fix	自动修复 ESLint 可处理的问题
pnpm lint:prettier	格式化代码、样式、JSON 和 Markdown
pnpm lint:stylelint	检查并修复 CSS、SCSS 和 Vue 样式
pnpm security:check	检查直接 v-html 和 localStorage.clear() 等高风险写法
pnpm build	先执行 vue-tsc --noEmit，再进行生产构建
pnpm release:check	依次执行安全检查、Lint 和生产构建

lint-staged 会在提交阶段处理本次变更文件，Commitizen 与 Commitlint 用于统一提交信息。推荐使用：

pnpm commit

提交类型包括 feat、fix、docs、refactor、perf、test、build、ci、chore 等。

项目编码约定

页面与业务逻辑

• Vue 页面使用 <script setup lang="ts">。
• 普通列表页优先复用 useTable，不要在每页重写分页状态机。
• 搜索、弹窗和复杂局部模块放在当前页面的 modules/ 中。
• 真实接口统一定义在 src/api，未迁移页面调用 src/mock；不要在组件或 src/services 中创建 Axios 请求。
• 接口函数优先采用 fetchXxx 命名，类型放在 src/types/api 的对应业务域。

路由与权限

• 路由名称全局唯一。
• 页面组件放在 src/views，动态组件路径以该目录为根。
• 新增按钮权限时同时维护 permissionPrefix、authList 和页面判断。
• 前端权限只控制交互，真实操作必须由后端再次鉴权。

样式

• 优先使用项目已有的 CSS 变量、Tailwind 主题色和 art-* 容器类。
• 不要在业务页面硬编码整套亮色与暗色颜色。
• Element Plus 的全局主题在 src/assets/styles/core 中统一维护。
• 页面应同时检查亮色、暗色、桌面端和移动端。

安全

• 动态 HTML 使用 ArtSafeHtml，禁止业务页面直接使用 v-html。
• 不要调用 localStorage.clear()，应按应用命名空间清理。
• 所有 VITE_ 变量都会进入浏览器产物，不得存放密钥。
• 模型密钥、对象存储密钥、支付密钥和数据库凭据必须放在服务端。

升级依赖的建议流程

升级 Vue、Vite、Element Plus 或 TypeScript 等核心依赖时，建议：

1. 单独创建升级分支，不与业务需求混合。
2. 阅读上游 Breaking Changes。
3. 更新依赖并保留锁文件差异。
4. 执行 pnpm release:check。
5. 手工验证登录、动态路由、表格、弹窗、主题切换和生产预览。
6. 检查构建产物是否出现异常大 Chunk 或样式覆盖。

下一步可以阅读系统架构，了解这些技术如何在运行时协作；工程约束和发布检查详见代码规范，自动注册的复用能力见通用组件与Hooks 与组合式能力。