250 lines
5.7 KiB
Markdown
250 lines
5.7 KiB
Markdown
# 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)。 |