官网 Nuxt 项目

基于 Nuxt 4 的官网前端项目。

技术栈

• 框架: Nuxt 4 + Vue 3 + TypeScript
• 状态管理: Pinia + pinia-plugin-persistedstate
• UI 组件: Element Plus
• 样式: Tailwind CSS + SCSS
• SEO: @nuxtjs/seo
• OG 图片: nuxt-og-image + satori

目录结构

├── app/
│   ├── assets/styles/       # 全局样式
│   │   ├── main.css       # Tailwind CSS 入口
│   │   ├── variables.scss # SCSS 变量
│   │   └── mixins.scss    # SCSS 混入
│   ├── components/        # 组件
│   ├── composables/       # 组合式函数
│   │   ├── useRequest.ts  # 统一请求封装（$fetch）
│   │   └── useApiFetch.ts  # useFetch 封装
│   ├── pages/             # 页面
│   │   └── index.vue      # 首页
│   ├── plugins/           # 插件
│   │   └── rem.ts         # 响应式 rem 方案
│   ├── stores/            # Pinia 状态库
│   │   └── user.ts        # 用户状态
│   └── app.vue            # 根组件
├── nuxt.config.ts         # Nuxt 配置
└── package.json

快速开始

安装依赖

npm install --legacy-peer-deps

开发

npm run dev

访问 http://localhost:8086

构建

npm run build

预览

npm run preview

主要功能

请求封装

项目中提供两种请求封装，根据场景选择使用。

useRequest（基于 $fetch）

• 默认 POST 方法
• 返回 { data, error }，需要 await
• ⚠️ 注意：基于 $fetch，SSR 时会重复请求（服务端一次 + 客户端一次），不适合页面初始数据加载
• 适用于：表单提交、按钮点击触发的一次性请求

// 表单提交
const { data, error } = await useRequest('/api/login', {
  body: { username, password }
})

// 指定其他方法
const { data } = await useRequest('/api/user', {
  method: 'PUT',
  body: { id, name }
})

useApiFetch（基于 useFetch）

• 默认 GET 方法
• 返回 { data, error, pending, refresh }，支持响应式
• ✅ SSR 友好：服务端预取数据，客户端自动复用，支持 hydration 优化
• 适用于：页面初始数据加载、需要响应式的数据获取

// 页面初始数据加载（推荐）
const { data, pending } = await useApiFetch<User[]>('/api/users', {
  query: { page: 1, size: 10 }
})

// 响应式查询
const { data } = useApiFetch('/api/user', {
  query: computed(() => ({ id: userId.value }))
})

// 需要刷新数据
const { data, refresh } = await useApiFetch('/api/list')
refresh() // 重新获取

SSR 安全说明

| 问题 | $fetch/useRequest | useFetch/useApiFetch | |------|------------------|---------------------| | SSR 预取 | ❌ 无 | ✅ 有 | | 客户端复用 | ❌ 无 | ✅ 有 | | 重复请求 | ❌ 服务端 + 客户端各一次 | ✅ 只在服务端 |

使用建议

• 页面初始化数据加载 → useApiFetch ✅
• 表单提交/按钮点击 → useRequest ✅
• 需要请求取消/刷新 → useApiFetch

响应式 Rem

基于设计稿的响应式字体大小方案：

• PC 端: 1920 设计稿，宽度 >= 1200px 时生效
• 移动端: 1080 设计稿，宽度 < 1200px 时生效

// px 转 rem
const fontSize = px2rem(32) // 0.32rem

SEO 优化

使用 @nuxtjs/seo 自动生成 SEO 相关 meta 标签：

<script setup lang="ts">
useSeoMeta({
  title: '页面标题',
  description: '页面描述',
})

useHead({
  title: '页面标题',
})
</script>

Open Graph 图片

使用 nuxt-og-image 生成社交分享图片：

<template>
  <OgImage title="页面标题" description="页面描述" />
</template>

Element Plus 组件

全局注册，可直接使用：

<template>
  <ElButton type="primary">按钮</ElButton>
  <ElInput v-model="input" placeholder="输入框" />
  <ElIcon><Search /></ElIcon>
</template>

Tailwind CSS

支持 Tailwind CSS 原子类：

<template>
  <div class="flex items-center justify-center p-4">
    <h1 class="text-2xl font-bold text-gray-800">官网</h1>
  </div>
</template>

Pinia 状态管理

带持久化的状态管理：

// stores/user.ts
export const useUserStore = defineStore('user', {
  // 状态定义
  state: () => ({
    token: null as string | null,
    userInfo: null as UserInfo | null,
  }),

  // 计算属性（getters）
  getters: {
    isLoggedIn: (state) => !!state.token && !!state.userInfo,
    getUsername: (state) => state.userInfo?.username || '',
  },

  // 方法（actions）
  actions: {
    login(token: string, info: UserInfo) {
      this.token = token
      this.userInfo = info
    },
    logout() {
      this.token = null
      this.userInfo = null
    },
  },
  // 持久化配置
  persist: {
    key: 'USER_INFO',
    storage: import.meta.client ? localStorage : undefined,
    pick: ['token', 'userInfo'],
  },
})

API 代理配置

开发环境通过 Vite 代理转发 API 请求：

// /api -> https://api.52game.cn

生产环境需配置对应的 API 地址。

开发规范

• 使用 TypeScript
• 组件使用 <script setup lang="ts">
• 样式优先使用 Tailwind CSS
• 复杂样式使用 SCSS 变量和混入
• 请求统一使用 useRequest
• 状态使用 Pinia 管理

VS Code 代码片段

项目提供了 Vue 3/Nuxt 的 VS Code 代码片段，位于 snippets/ 目录：

| 快捷键 | 描述 | |--------|------| | vue3 | Vue 3 组件完整模板 | | composable | Composable 函数模板 | | pstore | Pinia Store 模板 | | apireq | useRequest 请求封装 | | apifetch | useApiFetch 请求封装 | | seometa | SEO Meta 标签 | | ogimage | OgImage 组件 | | pagemeta | definePageMeta | | elform | Element Plus 表单 | | eltable | Element Plus 表格 | | eldialog | Element Plus 对话框 | | nupage | Nuxt 页面模板 | | nuapi | Nuxt API 路由 |

安装方法：将 snippets/vue3-snippets.code-snippets 复制到 .vscode 目录。

PM2 部署

项目提供了 ecosystem.config.js 配置文件，方便使用 PM2 管理项目。

常用命令

# 安装 PM2
npm install -g pm2

# 启动
pm2 start ecosystem.config.js

# 查看状态
pm2 list

# 查看日志
pm2 logs nuxt-app

# 重启
pm2 restart nuxt-app

# 停止
pm2 stop nuxt-app

# 删除进程
pm2 delete nuxt-app

# 开机自启
pm2 save
pm2 startup

修改端口

编辑 ecosystem.config.js 中的 PORT：

env: {
  PORT: 3000,  // 修改为你的端口
  NODE_ENV: 'production',
  HOST: '0.0.0.0',
},

日志位置

• 错误日志：logs/error.log
• 输出日志：logs/out.log
• 合并日志：logs/combined.log