ufutx-pc-website/README.md

# Vue 3 + TypeScript + Vite + Axios 基础框架

这是一个基于 **Vue 3**、**TypeScript** 和 **Vite** 的现代化前端基础框架，集成了 **Axios** 请求封装、**ESLint** 代码检查、**Prettier** 代码格式化等工具，帮助你快速搭建高质量的前端项目。


## 项目特性

- **核心框架**：Vue 3、Vue Router、Pinia（状态管理）
- **构建工具**：Vite 4（极速构建）
- **类型支持**：TypeScript 5（严格类型检查）
- **HTTP 请求**：Axios 封装（支持拦截器、错误处理、文件上传/下载）
- **代码规范**：ESLint + Prettier（统一代码风格）
- **样式方案**：Less（CSS 预处理）
- **提交规范**：Git 钩子（提交前自动检查代码）


## 快速开始

### 环境准备

- **Node.js**：v18+（推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理）
- **包管理器**：npm 或 pnpm


### 初始化项目

```bash
# 克隆仓库
git clone https://github.com/your-repo/vue3-ts-template.git
cd vue3-ts-template

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```


### 主要命令

| 命令            | 描述                            |
|-----------------|---------------------------------|
| `npm run dev`   | 启动开发服务器                  |
| `npm run build` | 构建生产环境包                  |
| `npm run preview` | 预览生产环境包                |
| `npm run lint`  | 代码检查并自动修复              |
| `npm run format` | 使用 Prettier 格式化代码       |


## 目录结构

```
src/
├── api/           # API 请求封装
├── assets/        # 静态资源
├── components/    # 通用组件
├── router/        # 路由配置
├── store/         # 状态管理 (Pinia)
├── utils/         # 工具函数
│   └── request.ts # Axios 封装
├── views/         # 页面组件
├── App.vue        # 根组件
└── main.ts        # 入口文件
```


## HTTP 请求封装

框架已封装完整的 Axios 请求工具，支持 **GET**、**POST**、**PUT**、**DELETE**、**文件上传** 和 **文件下载**，内置错误处理。

### 使用示例

```typescript
import request from '@/utils/request'

// GET 请求
const fetchUsers = async () => {
  try {
    const res = await request.get('/api/users', { page: 1, limit: 10 })
    console.log('用户列表:', res)
  } catch (error) {
    console.error('请求失败:', error)
  }
}

// POST 请求
const createUser = async (data: any) => {
  try {
    const res = await request.post('/api/users', data)
    console.log('创建成功:', res)
  } catch (error) {
    console.error('创建失败:', error)
  }
}

// 文件上传
const uploadFile = async (file: File) => {
  try {
    const res = await request.upload('/api/upload', file)
    console.log('上传成功:', res)
  } catch (error) {
    console.error('上传失败:', error)
  }
}

// 文件下载
const downloadFile = async () => {
  try {
    await request.download('/api/download/report', null, '报告.pdf')
    console.log('下载完成')
  } catch (error) {
    console.error('下载失败:', error)
  }
}
```


## 代码规范

### ESLint + Prettier

框架使用 ESLint 和 Prettier 统一代码风格，配置文件：

- `.eslintrc.cjs`：ESLint 规则
- `.prettierrc.cjs`：Prettier 规则

### 自动格式化

推荐在 VSCode 中安装以下插件，实现保存时自动格式化：

- ESLint
- Prettier
- Volar


## 状态管理

使用 **Pinia** 作为状态管理工具，示例：

```typescript
// store/userStore.ts
import { defineStore } from 'pinia'
import request from '@/utils/request'

export const useUserStore = defineStore('user', {
  state: () => ({
    userList: [],
    loading: false,
    error: null
  }),
  actions: {
    async fetchUsers() {
      this.loading = true
      try {
        const res = await request.get('/api/users')
        this.userList = res
      } catch (error) {
        this.error = error
      } finally {
        this.loading = false
      }
    }
  }
})
```


## 部署

### 构建生产环境包

```bash
npm run build
```

构建后的文件会输出到 `dist` 目录。


### 部署到 GitHub Pages

```bash
npm run deploy
```

需先配置 `package.json` 中的 `homepage` 字段。


## 常见问题

### 1. Axios 请求拦截器类型错误

如果遇到 `InternalAxiosRequestConfig` 类型错误，请确保：

1. 导入正确的类型：
   ```typescript
   import { type InternalAxiosRequestConfig } from 'axios'
   ```

2. 请求拦截器使用正确的类型：
   ```typescript
   service.interceptors.request.use(
     (config: InternalAxiosRequestConfig) => {
       // ...
       return config
     }
   )
   ```


### 2. 跨域问题

在开发环境中，可通过 `vite.config.ts` 配置代理：

```typescript
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})
```
``
目前的基础框架默认不包含 PC 端和移动端适配 的配置，需要根据项目需求添加相应方案。以下是几种常见的适配方法及其实现步骤：
一、现有框架适配状态
你的项目当前是 基础框架，未集成任何适配方案，默认行为是：
PC 端：按设计稿尺寸直接渲染，大屏幕可能显得紧凑。
移动端：内容可能过大，需要手动缩放或滚动查看
``

## 贡献指南

1. Fork 仓库
2. 创建特性分支：`git checkout -b feature/new-feature`
3. 提交代码：`git commit -m 'Add new feature'`
4. 推送分支：`git push origin feature/new-feature`
5. 提交 Pull Request


## 许可证

本项目采用 [MIT 许可证](LICENSE)。