# uniapp-v3-frame

**Repository Path**: start-programmer/uniapp-v3-frame

## Basic Information

- **Project Name**: uniapp-v3-frame
- **Description**: uniapp vite-ts 模版代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uni-app-v3-frame

基于 Vue 3 + TypeScript + Vite 的多端开发框架，采用现代化架构设计，提供开箱即用的开发体验。

## ✨ 特性

- ⚡ **Vite 构建** - 极速开发体验，热更新秒开
- 🎯 **TypeScript** - 完整的类型支持，代码更安全
- 🎨 **UnoCSS** - 原子化 CSS，灵活高效
- 📱 **多端支持** - 一套代码，多端运行（H5、小程序、App）
- 🔌 **自动导入** - 组件和 API 自动导入，开发更便捷
- 🌐 **国际化** - 内置 i18n 支持
- 🔒 **请求拦截** - 完善的 HTTP 请求封装和拦截器
- 📦 **模块化** - 清晰的目录结构，模块化设计
- 🍍 **Pinia** - Vue 3 官方状态管理，支持持久化

## 🛠️ 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.x | Composition API |
| TypeScript | 5.x | 类型安全 |
| Vite | 5.x | 极速构建工具 |
| Uni-app | 3.x | 多端开发框架 |
| UnoCSS | 0.x | 原子化 CSS 引擎 |
| Axios | 1.x | HTTP 请求库 |
| Pinia | 2.x | 状态管理库 |

## 📦 项目结构

```
uniapp-v3-ai/
├── src/
│   ├── api/                    # API 接口层
│   │   ├── types/              # API 类型定义
│   │   └── home.ts             # 首页 API 示例
│   ├── hooks/                  # 自定义 Hooks
│   │   ├── index.ts
│   │   └── useSafeArea.ts      # 安全区域 Hook
│   ├── http/                   # HTTP 请求封装
│   │   ├── config.ts           # 请求配置
│   │   ├── http.ts             # Axios 实例
│   │   ├── index.ts            # 统一导出
│   │   ├── interceptors.ts     # 拦截器
│   │   └── request.ts          # 请求方法
│   ├── layouts/                # 布局组件
│   │   └── default.vue
│   ├── pages/                  # 页面组件
│   │   └── index/
│   │       └── index.vue
│   ├── static/                 # 静态资源
│   ├── styles/                 # 全局样式
│   │   ├── index.scss
│   │   └── reset.scss
│   ├── utils/                  # 工具函数
│   │   ├── env.ts              # 环境变量工具
│   │   └── safeArea.ts         # 安全区域工具
│   ├── stores/                 # Pinia 状态管理
│   │   ├── index.ts            # Pinia 实例
│   │   └── modules/            # Store 模块
│   │       ├── user.ts         # 用户状态
│   │       └── app.ts          # 应用状态
│   ├── App.vue                 # 根组件
│   ├── main.ts                 # 入口文件
│   ├── env.d.ts                # 环境变量类型声明
│   ├── manifest.json           # 应用配置
│   └── pages.json              # 页面配置
├── .env                        # 全局环境变量
├── .env.development            # 开发环境变量
├── .env.production             # 生产环境变量
├── .env.test                   # 测试环境变量
├── manifest.config.ts          # Manifest 配置
├── pages.config.ts             # 页面配置
├── uno.config.ts               # UnoCSS 配置
├── vite.config.ts              # Vite 配置
└── package.json
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.x
- pnpm >= 8.x

### 安装依赖

```bash
pnpm install
```

### 启动开发服务器

```bash
# H5 开发
pnpm run dev:h5

# 微信小程序开发
pnpm run dev:mp-weixin

# 支付宝小程序开发
pnpm run dev:mp-alipay

# 指定平台开发
pnpm run dev:custom mp-weixin
```

### 构建生产版本

```bash
# H5 构建
pnpm run build:h5

# 微信小程序构建
pnpm run build:mp-weixin

# 支付宝小程序构建
pnpm run build:mp-alipay
```

## 📝 使用指南

### 1. HTTP 请求使用

```typescript
import { request } from '@/http'

// GET 请求
const data = await request.get<UserInfo>('/user/info')

// POST 请求
const result = await request.post('/user/create', { name: 'test' })

// 文件上传
const uploadResult = await request.upload('/api/upload', filePath, { key: 'value' })
```

### 2. 环境变量使用

```typescript
import { API_BASE_URL, APP_VERSION, isDev } from '@/utils/env'

console.log(API_BASE_URL)
console.log(APP_VERSION)
console.log(isDev)
```

### 3. 自定义 Hook 使用

```typescript
import { useSafeArea } from '@/hooks'

const { safeArea, update } = useSafeArea()
console.log(safeArea.value.statusBarHeight)
console.log(safeArea.value.safeAreaBottom)
```

### 4. API 调用示例

```typescript
import { getHomeData, getArticleList } from '@/api/home'

// 获取首页数据
const homeData = await getHomeData()

// 获取文章列表
const articles = await getArticleList({ page: 1, pageSize: 10 })
```

### 5. Pinia Store 使用

```typescript
import { useUserStore, useAppStore } from '@/stores'

// 用户状态
const userStore = useUserStore()
console.log(userStore.isLoggedIn)
console.log(userStore.userName)

// 登录
userStore.login(token, userInfo)

// 应用状态
const appStore = useAppStore()
console.log(appStore.theme)
console.log(appStore.isDark)

// 切换主题
appStore.toggleTheme()
```

## 🔧 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VITE_APP_PORT` | 开发服务器端口 | 8080 |
| `VITE_APP_TITLE` | 应用标题 | uniapp-v3-frame |
| `VITE_API_BASE_URL` | API 基础地址 | /api |
| `VITE_UNI_APPID` | Uni-app AppID | __UNI__xxxxxxxx |
| `VITE_WX_APPID` | 微信小程序 AppID | wx |
| `VITE_FALLBACK_LOCALE` | 默认语言 | zh-Hans |

### 修改配置

1. **开发端口**：编辑 `.env` 文件中的 `VITE_APP_PORT`
2. **API 地址**：编辑对应环境文件中的 `VITE_API_BASE_URL`
3. **应用配置**：编辑 `manifest.config.ts`

## 📱 支持平台

- [x] H5
- [x] 微信小程序
- [x] 支付宝小程序
- [x] 百度小程序
- [x] 字节跳动小程序
- [x] QQ 小程序
- [x] 快手小程序
- [x] 京东小程序
- [x] 5+ App
- [x] 小程序（头条）

## 🎨 代码风格

项目采用以下代码规范：

- 使用 TypeScript 编写所有代码
- 组件使用 Composition API (`<script setup>`)
- 使用 ES Module 语法
- 遵循 Vue 3 官方风格指南

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 👥 开发团队

基于 uni-app 官方模板优化，由社区共同维护。

## 🔗 相关链接

- [Vue 3 文档](https://vuejs.org/)
- [Uni-app 文档](https://uniapp.dcloud.net.cn/)
- [Vite 文档](https://vitejs.dev/)
- [TypeScript 文档](https://www.typescriptlang.org/)
- [UnoCSS 文档](https://unocss.dev/)