✨ Vue SSR 企业级开发模板 ✨

🚀 为 AI 协作而生的 Nuxt SSR 项目模板
📦 开箱即用，内置清晰分层、登录示例、文档入口和质量门禁
🔧 集成 Nuxt 4、Pinia、shadcn-vue、测试体系和提交规范

---

这是 create-wl-app 的企业级 Vue SSR 模板。项目基于 Nuxt 4 + Vue 3 构建，默认提供服务端渲染边界、登录示例、开发文档页、shadcn-vue + Tailwind CSS 现代 UI 栈、统一 API 封装、组件测试、E2E 和提交规范，适合团队和 AI Agent 稳定扩展业务代码。

🚀 技术栈

• SSR 框架：Nuxt 4.5.1
• 前端框架：Vue 3.5.40
• 开发语言：TypeScript 6.0.3
• 状态管理：Pinia 3.0.4 + @pinia/nuxt 0.11.3
• UI 组件库：shadcn-vue + reka-ui
• 样式方案：Tailwind CSS 4.3.3 + Sass
• 图标方案：Heroicons + @lucide/vue 1.28.0
• 代码规范：Oxlint 1.77.0 + ESLint 10.8.0 + oxfmt 0.62.0
• 提交规范：simple-git-hooks + lint-staged + commitlint
• API 封装：Axios 1.19.0
• 测试体系：Vitest + Testing Library Vue + Playwright + MSW + jest-axe

📦 快速开始

环境要求

• Node.js 24.18.0（Krypton LTS；支持范围 ^24.18.0）
• pnpm 11.20.0

安装依赖

pnpm install

启动开发服务器

pnpm dev

开发服务器默认运行在 http://localhost:3000。

项目打包与预览

pnpm build
pnpm preview

生产构建输出到 .output。

📁 项目结构

src/
├── pages/             # Nuxt 页面入口
├── layouts/           # 应用布局
├── features/          # 业务功能模块，如 auth、docs
├── shared/            # 跨业务基础能力，如 ui、api、lib、composables
├── server/            # server-only helpers 和 Nitro-oriented code
├── stores/            # Pinia stores
└── test/              # Vitest setup、render helper 和测试工具
tests/e2e/             # Playwright E2E 用例

主要目录说明

• pages/：Nuxt 路由入口，保持页面薄入口
• layouts/：应用级布局，页面可通过 definePageMeta 控制布局
• features/：业务模块，模块内聚页面、组件、store、api 和业务逻辑
• features/auth/：登录示例和 client-safe session 行为
• features/docs/：模板文档页，用于说明 SSR 边界、目录职责和依赖职责
• shared/ui/：shadcn-vue 基础组件，禁止放业务逻辑
• shared/api/：HTTP 基础设施和请求封装
• shared/lib/：跨业务纯工具函数
• server/：服务端专属能力，存放不能进入客户端 bundle 的逻辑

🎯 核心功能

🌐 SSR 路由

• ✅ 使用 Nuxt 文件路由管理页面入口
• ✅ Nuxt SSR 默认启用，浏览器能力通过 .client、onMounted 或 import.meta.client 隔离
• ✅ 登录和文档示例保持 SSR-safe，不在服务端读取浏览器存储
• ✅ Playwright 针对生产预览服务验证真实路由和 hydration

🔐 登录示例

• ✅ 提供模板级登录页和 session 示例
• ✅ Demo token 仅在客户端安全交互中写入浏览器存储
• ✅ 真实业务 SSR 登录建议改用 cookie 或请求头

🎨 UI 与样式

• ✅ 使用 Tailwind CSS 作为默认样式方案
• ✅ shadcn-vue 基础组件统一放在 src/shared/ui
• ✅ Heroicons 和 @lucide/vue 按需导入
• ✅ 业务组件放在各自 feature 内，避免污染基础组件目录

🔌 API 封装

• ✅ 基于 Axios 的统一请求封装
• ✅ 业务请求优先走 src/shared/api
• ✅ server-only 请求上下文放在 src/server
• ✅ 避免在页面中散落 raw fetch 或 Axios 实例

📐 代码规范

• ✅ Oxlint + ESLint + oxfmt 保持代码质量和格式稳定
• ✅ simple-git-hooks + lint-staged 处理提交前检查
• ✅ commitlint 校验 Conventional Commit 信息
• ✅ Nuxt 类型检查，提交前可运行 pnpm typecheck

🧪 测试与质量门禁

常用测试命令

# 单元测试、组件测试、a11y 测试
pnpm test

# 覆盖率门禁
pnpm test:coverage

# 生成 JUnit 报告，供 CI 读取
pnpm test:junit

# 检查新增/修改组件是否有组件测试
pnpm test:component-coverage

# Playwright E2E 冒烟测试
pnpm test:e2e

提交前建议验证

pnpm test
pnpm test:coverage
pnpm test:component-coverage
pnpm typecheck
pnpm lint
pnpm test:e2e
pnpm build

测试约定

• 新增或修改组件时，必须同步新增或更新组件测试；每个组件至少保留一个 render smoke test。
• 业务逻辑、session、navigation、API wrapper 等非 UI 能力应补单元测试。
• 网络请求测试使用 MSW，不在测试中请求真实后端。
• 页面级无障碍测试使用 jest-axe，E2E 冒烟测试使用 Playwright。
• 覆盖率报告输出到 coverage/；Vitest/Playwright JUnit 报告输出到 test-results/；Playwright HTML 报告输出到 playwright-report/。

🛠️ 开发调试开关

页面元素定位源码

默认保持关闭，需要在真实环境变量中开启；.env.example 仅作为说明，不会自动生效。

NUXT_ENABLE_CODE_INSPECTOR=true pnpm dev

macOS 按住 shift + option，Windows 按住 shift + alt，点击页面元素即可打开对应源码位置。

复制源码位置

NUXT_ENABLE_CODE_INSPECTOR=true NUXT_CODE_INSPECTOR_ACTION=copy pnpm dev

NUXT_CODE_INSPECTOR_ACTION 支持 open、copy、both。

⚙️ 配置文件说明

配置文件	说明
nuxt.config.ts	Nuxt SSR 构建、模块和插件配置
eslint.config.mjs	ESLint 代码规范配置
vitest.config.ts	Vitest 单元和组件测试配置
playwright.config.ts	Playwright E2E 配置
components.json	shadcn-vue 组件配置
commitlint.config.cjs	Conventional Commit 校验配置

📝 提交规范

提交信息使用 Conventional Commits：

git add -A
git commit -m "feat: add auth page"
git pull --rebase
git push

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE。