🚀 Vue3 模板 —— 为 AI 而生的企业级项目模板

🌟 核心优势

• ✅ AI 友好 - 内置 AGENTS.md、docs 模块和 shadcn-vue skill，方便 AI Agent 快速理解项目边界
• ✅ 企业级分层 - app、features、shared 分层清晰，默认避免业务代码散落
• ⚡ 极致性能 - 基于 Vite 8.3.0 + Rolldown，构建速度飞起来
• 🎨 现代化 UI 栈 - 使用 shadcn-vue + Tailwind CSS + Heroicons 组织界面能力
• 🔧 开发友好 - 内置路由守卫、认证 session、API 封装、通知适配和代码规范

🛠️ 技术栈亮点

🔌 核心框架

• Vue 3.5.42 - 使用 Composition API 与 <script setup lang="ts"> 作为默认组件范式
• Vite 8.3.0 - 下一代前端构建工具，基于 Rolldown 引擎
• TypeScript - 默认使用 .ts 与 Vue SFC 类型检查，提供更清晰的类型约束
• Vue Router 5.3 - feature 暴露 routes，由 src/app/routes 聚合

⚡ Vite 8.3 构建基线

• 入口配置更统一 - 新增顶层 input，插件解析后的入口会自动进入开发服务器文件白名单；模板仍使用标准 index.html，无需改动现有配置。
• 开发反馈更清晰 - bundled dev 改进 worker HMR、重建 reload 和终端错误输出；网络地址会标记对应网卡接口，方便局域网联调。
• 配置问题更易定位 - 原生配置加载兼容警告包含列号，并减少虚拟模块误报，复杂插件配置发生问题时可以更快找到具体位置。
• 构建边缘场景更稳健 - 修复 CSS chunk import map、PostCSS 注入内容 URL、优化依赖 interop、非根 base 模块图和符号链接根目录等问题。
• 依赖扫描减少无效工作 - 优先检查主流包管理器锁文件，并在忽略相关警告时跳过不必要的配置兼容检查；实际加速幅度取决于项目规模。

当前模板的 Vue、Tailwind CSS、legacy、压缩、Vite/Vue DevTools 与 code-inspector 插件组合已通过生产构建和 Playwright E2E。完整变更与模板验证见 2026-08-06 升级日志。

🎯 状态管理

• Pinia 4 - Vue 官方推荐状态管理库，应用级注册位于 src/app/stores
• pinia-plugin-persistedstate - 支持 session 等状态持久化能力

🎨 UI 与样式

• shadcn-vue - 基础组件源码统一放在 src/shared/ui，业务组件留在各自 feature
• Tailwind CSS 4 - 默认样式表达方式，替代旧 UnoCSS 配置
• Heroicons Vue - 从 @heroicons/vue/24/outline 按需导入业务图标
• reka-ui - 作为 shadcn-vue 复杂交互组件的无障碍底层能力
• vue-sonner - Toast 通知组件，业务侧通过 src/app/notifications 调用

🔄 网络请求

• axios - 统一封装在 src/shared/api/http.ts，负责 token 注入、响应解包和错误处理
• app/navigation - 统一处理未授权跳转和登录过期逻辑
• features/auth/session - token 读写只从认证模块边界进入

🧭 默认模块

• auth - 登录页、OGL 背景、session token 读写和认证相关接口
• docs - 登录后的默认入口，用于说明项目结构、核心库职责和开发约定
• shared/ui - shadcn-vue primitives，只放基础组件，不放业务逻辑
• .agents/skills/shadcn-vue - 内置 shadcn-vue Agent skill，提升 AI 操作组件时的稳定性

🛠️ 开发工具

• vite-plugin-vue-devtools - 通过 VITE_ENABLE_VUE_DEVTOOLS=true 开启 Vue DevTools 插件
• @vitejs/devtools - 通过 VITE_ENABLE_DEVTOOLS=true 开启 Vite DevTools
• code-inspector-plugin - 通过 VITE_ENABLE_CODE_INSPECTOR=true 开启浏览器到 IDE 的代码定位
• ESLint + vue-tsc - 提交前建议执行 lint、typecheck 和 build 三道验证

🚀 快速开始

运行时统一使用 Node.js 24 LTS（Krypton），支持范围为 >=24.11.0 <25，推荐使用最新 24.x。

# 创建项目
npx cwa-stack create

? 请选择技术栈
  React
❯ Vue

? 请选择应用类型
❯ 单页面应用
  SSR 服务端渲染

? 请选择模板
❯ Vite Vue 3 企业级模板（vite-vue3）

? 请输入项目名称 my-vue3-app

? 请输入项目描述 一个基于 Vue3 的企业级项目模板

✔ 项目生成中...

项目生成成功

# 进入项目目录
cd my-vue3-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm run dev

# 构建生产版本
pnpm run build

💡 最佳实践

1. 模块归属 - 新业务放到 src/features/<name>，页面、组件、接口和 store 跟随 feature
2. 应用组合 - 路由、通知、导航、全局样式和全局 store 注册放在 src/app
3. 共享能力 - 跨业务 API、工具函数、运行配置和基础组件放在 src/shared
4. 样式开发 - 默认使用 Tailwind CSS；全局样式只放 src/app/styles
5. AI 协作 - 项目规则写入 AGENTS.md，新增目录前先确认业务或能力归属
6. 质量验证 - 提交前执行 pnpm lint、pnpm typecheck、pnpm build

📁 TypeScript 项目结构

src/
├── app/                  # 应用装配、路由、通知、导航、全局样式
│   ├── routes/           # 路由聚合、守卫、类型
│   ├── stores/           # 全局状态注册
│   ├── styles/           # Tailwind 与全局样式
│   ├── App.vue
│   └── setup.ts
├── features/             # 业务功能模块
│   ├── auth/             # 登录、session、认证接口
│   └── docs/             # 模板文档页
├── shared/               # 跨业务基础能力
│   ├── api/              # HTTP client
│   ├── components/       # 非 shadcn 的共享组件
│   ├── config/           # 运行配置
│   ├── lib/              # 工具函数
│   └── ui/               # shadcn-vue primitives
├── main.ts
└── vite-env.d.ts

⚙️ 环境变量

VITE_APP_NAME="初始化项目"
VITE_API_BASE="/API_BASE"
VITE_API_TARGET="http://localhost:8080"
VITE_ENABLE_VUE_DEVTOOLS=true
VITE_ENABLE_DEVTOOLS=false
VITE_ENABLE_CODE_INSPECTOR=false
VITE_ENABLE_COMPRESSION=true
VITE_ENABLE_LEGACY=true
VITE_ENABLE_WEB_UPDATE_NOTICE=false

🧩 shadcn-vue

配置文件为 components.json。添加组件时使用：

pnpm dlx shadcn-vue@latest add button card

组件默认生成到 src/shared/ui，工具函数使用 src/shared/lib/utils.ts。

✅ 类型检查

Vue3 模板源码默认使用 TypeScript，核心目录包括 src/app、src/features、src/shared。提交前建议执行：

pnpm run lint
pnpm run typecheck
pnpm run build

📚 文档资源

• GitHub 项目地址
• Gitee 项目地址
• Vue 3 官方文档
• Vue Router 文档
• Pinia 官方文档
• shadcn-vue 文档
• Tailwind CSS 文档
• Heroicons 文档
• Vite 官方文档

---

🎉 立即使用 cwa-stack，开启你的现代化 Vue3 企业级开发之旅！

🤖 AI 友好 | ⚡ 极致性能 | 🎨 现代 UI | 🔧 开发友好

🔐 真实登录与契约

Vue3 模板已与配套后端 springboot-template 形成真实登录闭环：

• 登录请求 POST /api/v1/login（username/password/remember），响应顶层 token/tokenType/expiresAt/user；API 前缀固定 /api/v1，开发代理按 /api 直通转发。
• API 类型与 Client 由后端 OpenAPI 3.1 契约生成（pnpm run api:generate，输出 src/shared/api/generated，禁止手工编辑）；契约快照位于 openapi/api-contract.yaml。
• 错误统一读取 Problem Details 顶层 code/msg/requestId；登录接口的 401 由登录页展示后端 msg，不触发会话过期流程。
• Mock 模式显式开启：VITE_ENABLE_MOCK=true 启用 MSW 浏览器 Mock（演示账号 admin/admin），生产构建保持关闭；模板 E2E 默认走 Mock，真实后端 E2E 用 E2E_AUTH_MOCK=false + E2E_AUTH_USERNAME/E2E_AUTH_PASSWORD 注入种子凭据。