# nuxt4-template

**Repository Path**: vinson007/nuxt4-template

## Basic Information

- **Project Name**: nuxt4-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nuxt Demo

基于 Nuxt 4 的前端项目，集成 TailwindCSS v4、shadcn-vue、GSAP + ScrollTrigger 动画库。

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Nuxt 4 + Vue 3 + TypeScript |
| 样式 | TailwindCSS v4（Vite 插件模式） |
| UI 组件库 | shadcn-vue (reka-nova) |
| 图标 | Lucide Vue |
| 动画 | GSAP 3 + ScrollTrigger |
| 通知 | vue-sonner |
| 格式化 | Biome + Prettier（Vue 文件） |
| 包管理 | pnpm |

## 快速开始

```bash
# 安装依赖
pnpm install

# 启动开发服务器 (http://localhost:3000)
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview
```

## 代码规范

```bash
pnpm lint         # 检查代码（Biome）
pnpm lint:fix     # 自动修复（Biome）
pnpm format       # 格式化（Biome + Prettier）
```

## 添加组件

```bash
# 添加 shadcn-vue 组件
pnpm dlx shadcn-vue@latest add button
pnpm dlx shadcn-vue@latest add dialog
pnpm dlx shadcn-vue@latest add input
```

组件会自动生成到 `app/components/ui/` 目录，Nuxt 自动导入，无需手动 import。

## 项目结构

```
app/
  assets/css/tailwind.css    # TailwindCSS 入口 + 主题变量
  components/
    ui/                      # shadcn-vue 组件（自动生成）
    homeSection/             # 首页版块（按页面分组，子版块自包含）
  composables/useApi.ts      # 统一接口封装（useApi / useApiList）
  types/api.ts               # 接口响应类型（ApiResult / ApiError）
  lib/utils.ts               # cn() 工具函数
  pages/                     # 页面路由
  plugins/gsap.client.ts     # GSAP + ScrollTrigger 客户端插件
  app.vue                    # 根组件（挂载全局 Sonner 通知）
server/
  api/[...path].ts           # BFF 统一代理（/api/* → 真实后端）
  utils/createServerApi.ts   # 服务端 $fetch 实例（注入 dbName、强制 JSON 解析）
.claude/skills/              # Claude Code 技能（figma-to-nuxt4-expert）
.env                         # 后端域名 / 数据库名（已 git 忽略）
```

## 接口调用封装

采用「客户端封装 + 服务端 BFF 代理」分层架构：客户端 `useApi` / `useApiList` 统一处理 baseURL、业务码校验（`code === '1'`）、错误 toast；服务端 BFF 转发到真实后端，隐藏后端地址、规避跨域、自动注入 `dbName`。

```ts
// 单对象（字段不确定，用 ?. 安全取）
const { data } = useApi<User>('/user/info')
const user = computed(() => data.value?.data)

// 列表 / 分页（字段不确定，内部用 ?? 兜底）
const { list, total, totalPage } = useApiList<BannerImage>('/oe_getBannerImages_.csp', {
  query: { module: 10 },
})
```

> 后端 `.csp` 接口返回 JSON 字符串（Content-Type 非标），BFF 已强制解析，调用方无感。

## 环境变量

复制 `.env.example` 为 `.env`（已 git 忽略）并填写后端连接信息：

```
NUXT_API_BASE=https://mdy.juesedao.com   # 真实后端域名（仅服务端可见）
NUXT_DB_NAME=compac                        # 数据库名，由 BFF 自动注入到每个请求的 query
```

## 静态部署（SSG）

项目已配置静态打包，构建时预渲染所有页面（接口数据在构建期通过 BFF 获取，写死到静态 HTML）：

```bash
pnpm generate                # 静态打包，产出 .output/public
npx serve .output/public     # 本地预览静态产物
```

产出 `.output/public` 为纯静态站点，可部署到任意静态托管（对象存储 / CDN / GitHub Pages 等）。

> **注意**：静态产物运行时无 Node server，BFF 仅在构建期生效。部署后接口数据为构建时的快照；若需运行时动态获取数据，请改用支持 server 的平台部署（如 Vercel / Netlify / Node）。

## 相关文档

- [Nuxt](https://nuxt.com/docs)
- [shadcn-vue](https://www.shadcn-vue.com/docs)
- [TailwindCSS v4](https://tailwindcss.com/docs)
- [GSAP](https://gsap.com/docs/)
- [Biome](https://biomejs.dev/)