# uniapp_vue3_vite_element_plus

**Repository Path**: ncepu-bj/uniapp_vue3_vite_element_plus

## Basic Information

- **Project Name**: uniapp_vue3_vite_element_plus
- **Description**: 微信小程序：
这是一个基于 Vue 3 + TypeScript + Uni-app 的微信小程序模板项目。

## 技术栈

- Vue 3：使用最新的 Vue.js 框架
- Vite：作为构建工具
- TypeScript：使用 TypeScript 进行开发
- uni-app：跨平台开发框架
- Element-Plus：UI组件库
- Pinia：状态管理
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-05
- **Last Updated**: 2025-11-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微信小程序模板项目

这是一个基于uni-app框架的，基于 Vue 3 + TypeScript + Vite 构建的微信小程序开发模板，提供完整的项目架构和开箱即用的开发体验。

注意：小程序在node.js的版本22.21.1下调试通过；

## 技术栈
- **node.js**- 在版本22.21.1下调试通过；npm使用10.9.4；
- **Vue 3.3** - 渐进式 JavaScript 框架，使用 Composition API
- **TypeScript 5.0** - 类型安全的 JavaScript 超集
- **Vite 5.2** - 下一代前端构建工具
- **uni-app 3.0** - 跨平台应用开发框架
- **Pinia 2.1** - Vue 官方状态管理库
- **Element Plus 2.4** - 基于 Vue 3 的组件库
- **Sass** - CSS 预处理器

## 项目结构

```
wx-mini-template/
├── src/
│   ├── api/                    # API 接口层
│   │   ├── common.ts          # 通用接口（上传、配置等）
│   │   ├── user.ts            # 用户相关接口
│   │   ├── types.ts           # 接口类型定义
│   │   └── index.ts           # 统一导出
│   ├── config/                 # 配置文件
│   │   ├── env.ts             # 环境配置（开发/生产）
│   │   └── index.ts           # 全局配置（应用名称、版本等）
│   ├── pages/                  # 页面目录
│   │   ├── home/              # 首页
│   │   ├── learn/             # 学习模块
│   │   │   ├── index.vue      # 学习主页
│   │   │   └── word-study/    # 单词学习页面
│   │   ├── discover/          # 发现页（课程）
│   │   └── mine/              # 我的页面
│   ├── static/                 # 静态资源
│   │   └── tabbar/            # 底部导航图标
│   ├── stores/                 # Pinia 状态管理
│   │   └── user.ts            # 用户状态
│   ├── utils/                  # 工具函数
│   │   └── request.ts         # 网络请求封装
│   ├── App.vue                # 应用入口组件
│   ├── main.ts                # 主入口文件
│   ├── manifest.json          # uni-app 应用配置
│   ├── pages.json             # 页面路由配置
│   └── uni.scss               # 全局样式变量
├── docs/                       # 项目文档
│   ├── TABBAR_ICONS.md        # 底部导航图标配置指南
│   └── SASS_FIXES.md          # Sass 配置文档
├── scripts/                    # 脚本工具
│   └── convert-svg-to-png.js  # SVG 转 PNG 工具
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
└── package.json               # 项目依赖
```

## 核心功能

### 1. 完整的 TypeScript 支持
- 严格的类型检查
- 完善的类型定义
- 智能代码提示

### 2. 状态管理（Pinia）
位于 `src/stores/user.ts`，提供：
- 用户信息管理
- 登录状态持久化
- 类型安全的 store

### 3. 网络请求封装
位于 `src/utils/request.ts`，特性：
- Promise 风格的 API
- 统一的错误处理
- 自动添加请求头
- 支持 GET、POST、PUT、DELETE 方法

### 4. API 接口层
- **用户接口**（`src/api/user.ts`）：登录、获取/更新用户信息、退出登录
- **通用接口**（`src/api/common.ts`）：文件上传、获取配置
- **类型定义**（`src/api/types.ts`）：统一的接口类型和响应格式

### 5. 环境配置
位于 `src/config/env.ts`，支持：
- 开发环境配置
- 生产环境配置
- 自动切换 API 地址

### 6. 底部导航栏
预设四个主要页面，配置在 `src/pages.json`：
- 首页（pages/home/index）
- 学习（pages/learn/index）- 单词学习模块
- 课程（pages/discover/index）
- 我的（pages/mine/index）

### 7. 学习模块
位于 `src/pages/learn/`，提供：
- **学习主页**：显示当前学习计划、今日应学单词数
- **单词学习页**：单词详情、发音、例句、用法展示
- **交互功能**：认识/不认识标记、发音播放

### 8. Vite 构建优化
- 路径别名（@ 指向 src）
- Terser 压缩（生产环境移除 console）
- 现代 Sass 编译器（modern-compiler）
- 禁用弃用警告（legacy-js-api、import）
- 开发服务器配置

## 快速开始

### 环境要求

- Node.js >= 16.0.0（推荐使用 LTS 版本）
- pnpm >= 7.0.0（推荐）或 npm >= 8.0.0
- 微信开发者工具

> 已在 Node.js 22.21.1 + pnpm 9.0.0 环境下测试通过

### 安装 pnpm（推荐）

如果还没有安装 pnpm，可以使用以下方式安装：

```bash
# 使用 npm 安装 pnpm
npm install -g pnpm

# 或使用 PowerShell（Windows）
iwr https://get.pnpm.io/install.ps1 -useb | iex

# 或使用 Homebrew（macOS）
brew install pnpm

# 验证安装
pnpm -v
```

### 安装依赖

```bash
# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install --legacy-peer-deps
```

### 配置 TabBar 图标

项目需要 PNG 格式的底部导航图标才能正常显示。快速创建图标：

```bash
# 打开图标生成器（推荐）
pnpm run icons:create

# 或检查图标状态
pnpm run icons:check
```

详细说明请查看：[TabBar 图标配置指南](docs/TABBAR_ICONS.md)

### 开发调试

```bash
# 启动开发服务器
pnpm run dev

# 类型检查
pnpm run type-check
```

### 构建发布

```bash
# 构建微信小程序
pnpm run build
```

### 导入微信开发者工具

1. 打开微信开发者工具
2. 导入项目，选择 `dist/dev/mp-weixin` 目录（开发环境）或 `dist/build/mp-weixin` 目录（生产环境）
3. 填写 AppID（在 `src/manifest.json` 中配置）
4. 开始调试

## 配置说明

### 修改应用信息

编辑 `src/manifest.json`：

```json
{
  "name": "你的应用名称",
  "appid": "你的微信小程序 AppID",
  "versionName": "1.0.0"
}
```

### 配置 API 地址

编辑 `src/config/env.ts`：

```typescript
export const ENV = {
  development: {
    BASE_API: 'http://your-dev-api.com',
    UPLOAD_URL: 'http://your-dev-upload.com'
  },
  production: {
    BASE_API: 'https://your-api.com',
    UPLOAD_URL: 'https://your-upload.com'
  }
}
```

### 样式配置

项目使用现代 Sass 编译器（modern-compiler），已配置禁用弃用警告。

**Sass 配置特性：**
- 使用 `api: 'modern-compiler'` 启用现代编译器
- 禁用 `legacy-js-api` 和 `import` 弃用警告
- 支持 SCSS 语法和嵌套规则

如需使用全局样式变量，可在组件中手动引入：

```scss
<style lang="scss" scoped>
@import "@/uni.scss";

.example {
  color: $primary-color; // 主题色
  padding: $spacing-base; // 间距变量
}
</style>
```

可用的全局变量请查看 `src/uni.scss`

### 添加新页面

1. 在 `src/pages/` 下创建页面目录和 `index.vue`
2. 在 `src/pages.json` 中注册页面路由

```json
{
  "pages": [
    {
      "path": "pages/your-page/index",
      "style": {
        "navigationBarTitleText": "页面标题"
      }
    }
  ]
}
```

## 开发规范

### 代码风格

- 使用 TypeScript 进行开发
- 遵循 Vue 3 Composition API 规范
- 使用 `<script setup>` 语法糖
- 组件和文件使用 PascalCase 或 kebab-case 命名

### 类型定义

- API 接口类型定义在 `src/api/types.ts`
- Store 类型定义在各自的 store 文件中
- 公共类型可在 `src/types/` 目录下定义

### 目录规范

- `api/` - 按业务模块划分接口文件
- `pages/` - 每个页面一个独立目录
- `stores/` - 按功能模块划分 store
- `utils/` - 通用工具函数

## 常见问题

### 依赖安装失败

如果遇到 `ERESOLVE` 错误：

```bash
# 使用 pnpm（推荐，自动处理依赖冲突）
pnpm install

# 或使用 npm
npm install --legacy-peer-deps
```

### 微信开发者工具无法预览

1. 检查是否已在 `manifest.json` 中配置 AppID
2. 确认微信开发者工具已开启服务端口
3. 检查项目路径是否正确（应指向 dist 目录）

### TypeScript 类型错误

运行类型检查命令：

```bash
pnpm run type-check
```

## 推荐开发工具

- **VSCode** - 代码编辑器
- **Volar** - Vue 3 官方 VSCode 插件
- **TypeScript Vue Plugin (Volar)** - TypeScript 支持
- **微信开发者工具** - 小程序调试

## 版本信息

- 项目版本：1.0.0
- Vue：^3.3.0
- TypeScript：^5.0.0
- Vite：^5.2.8
- uni-app：^3.0.0-alpha-3080720230703001
- Pinia：^2.1.0
- Element Plus：^2.4.0

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个模板。

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/AmazingFeature`）
3. 提交改动（`git commit -m 'Add some AmazingFeature'`）
4. 推送到分支（`git push origin feature/AmazingFeature`）
5. 提交 Pull Request

## 许可证

[MIT License](LICENSE)