forked from gxwebsoft/mp-10550
593 lines
17 KiB
Markdown
593 lines
17 KiB
Markdown
<div align="center">
|
||
<h1>🚀 WebSoft 小程序</h1>
|
||
<p><strong>基于 Taro + React + TypeScript 的跨平台小程序应用</strong></p>
|
||
|
||
<p>
|
||
<img src="https://img.shields.io/badge/Taro-4.0.8-blue" alt="Taro">
|
||
<img src="https://img.shields.io/badge/React-18.3.1-61DAFB" alt="React">
|
||
<img src="https://img.shields.io/badge/TypeScript-5.7.2-3178C6" alt="TypeScript">
|
||
<img src="https://img.shields.io/badge/NutUI-3.0.16-orange" alt="NutUI">
|
||
<img src="https://img.shields.io/badge/TailwindCSS-3.4.17-38B2AC" alt="TailwindCSS">
|
||
<img src="https://img.shields.io/badge/License-MIT-blue" alt="License">
|
||
</p>
|
||
</div>
|
||
|
||
## 📖 项目简介
|
||
|
||
WebSoft 小程序是一个基于 **Taro + React + TypeScript** 构建的现代化跨平台小程序应用，支持多端发布：
|
||
|
||
- **核心框架**：Taro 4.0.8 + React 18.3.1 + TypeScript 5.7.2
|
||
- **UI组件库**：NutUI React Taro 2.7.4 + NutUI Icons
|
||
- **样式方案**：Sass + TailwindCSS 3.4.17
|
||
- **状态管理**：React Hooks + Context API
|
||
- **工具库**：Day.js、Crypto-js、React Router DOM
|
||
|
||
## 🎯 支持平台
|
||
|
||
本项目基于 Taro 框架，支持一套代码多端运行：
|
||
|
||
- **微信小程序** (weapp)
|
||
- **支付宝小程序** (alipay)
|
||
- **百度智能小程序** (swan)
|
||
- **字节跳动小程序** (tt)
|
||
- **QQ小程序** (qq)
|
||
- **京东小程序** (jd)
|
||
- **H5网页** (h5)
|
||
- **React Native** (rn)
|
||
- **快应用** (quickapp)
|
||
|
||
|
||
|
||
## 项目演示
|
||
| 后台管理系统 | https://mp.websoft.top |
|
||
|--------|-------------------------------------------------------------------------------------------------------------------------------------|
|
||
| 演示账号 | 请联系开发者获取演示账号
|
||
| 正式账号 | [立即注册](https://mp.websoft.top/register/?inviteCode=github) |
|
||
| 关注公众号 |  |
|
||
|
||
|
||
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
### 核心框架
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Taro | 4.0.8 | 跨平台开发框架 |
|
||
| React | 18.3.1 | 前端UI框架 |
|
||
| TypeScript | 5.7.2 | 类型安全的JavaScript |
|
||
| Webpack | 5.78.0 | 模块打包工具 |
|
||
| Babel | 7.26.0 | JavaScript编译器 |
|
||
| PostCSS | 8.4.49 | CSS后处理器 |
|
||
| ESLint | 8.57.1 | 代码质量检查 |
|
||
|
||
### UI组件库
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| NutUI React Taro | 2.7.4 | 移动端组件库 |
|
||
| NutUI Icons | 2.0.1 | 图标库 |
|
||
| NutUI Biz | 1.0.0-beta.2 | 业务组件库 |
|
||
|
||
### 样式方案
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Sass | - | CSS预处理器 |
|
||
| TailwindCSS | 3.4.17 | 原子化CSS框架 |
|
||
| Autoprefixer | 10.4.20 | CSS自动前缀 |
|
||
|
||
### 功能组件
|
||
- **React Router DOM** - 路由管理
|
||
- **Day.js** - 日期时间处理
|
||
- **Crypto-js** - 加密解密工具
|
||
- **js-base64** - Base64编码解码
|
||
- **React Markdown** - Markdown渲染
|
||
- **ECharts Taro3 React** - 图表组件
|
||
|
||
## 📋 环境要求
|
||
|
||
### 基础环境
|
||
- 📦 **Node.js 16+**
|
||
- 📱 **微信开发者工具** (开发微信小程序)
|
||
- 🔧 **支付宝开发者工具** (开发支付宝小程序)
|
||
- 🌐 **现代浏览器** (开发H5应用)
|
||
|
||
### 包管理器
|
||
- **npm** / **yarn** / **pnpm** (推荐使用pnpm)
|
||
|
||
### 开发工具
|
||
- **推荐**：VS Code / WebStorm
|
||
- **插件**：ES7+ React/Redux/React-Native snippets、TypeScript Importer
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 克隆项目
|
||
```bash
|
||
git clone https://github.com/websoft-top/mp-taro.git
|
||
cd mp-taro
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
```bash
|
||
# 使用 pnpm (推荐)
|
||
pnpm install
|
||
|
||
# 或使用 npm
|
||
npm install
|
||
|
||
# 或使用 yarn
|
||
yarn install
|
||
```
|
||
|
||
### 3. 配置开发环境
|
||
|
||
#### 环境变量配置
|
||
项目支持多环境配置，通过 `config/env.ts` 文件管理不同环境的配置：
|
||
|
||
```typescript
|
||
// config/env.ts
|
||
export const ENV_CONFIG = {
|
||
// 开发环境
|
||
development: {
|
||
API_BASE_URL: 'http://localhost:3000/api',
|
||
APP_NAME: 'Taro App Dev',
|
||
DEBUG: 'true',
|
||
},
|
||
// 生产环境
|
||
production: {
|
||
API_BASE_URL: 'https://api.example.com',
|
||
APP_NAME: 'Taro App',
|
||
DEBUG: 'false',
|
||
},
|
||
// 测试环境
|
||
test: {
|
||
API_BASE_URL: 'https://test-api.example.com',
|
||
APP_NAME: 'Taro App Test',
|
||
DEBUG: 'true',
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 应用配置
|
||
编辑 `config/app.ts` 文件，配置租户ID等信息：
|
||
```typescript
|
||
export const TenantId = 'your_tenant_id'
|
||
export const BaseUrl = API_BASE_URL // 自动从环境配置读取
|
||
```
|
||
|
||
### 4. 启动开发服务器
|
||
|
||
#### 微信小程序开发
|
||
```bash
|
||
# 开发环境（默认）
|
||
npm run dev:weapp
|
||
|
||
# 生产环境
|
||
NODE_ENV=production npm run dev:weapp
|
||
|
||
# 测试环境
|
||
NODE_ENV=test npm run dev:weapp
|
||
```
|
||
然后使用微信开发者工具打开 `dist` 目录
|
||
|
||
#### H5开发
|
||
```bash
|
||
# 启动H5开发模式
|
||
npm run dev:h5
|
||
```
|
||
访问 `http://localhost:10086` 查看H5版本
|
||
|
||
#### 其他平台
|
||
```bash
|
||
# 支付宝小程序
|
||
npm run dev:alipay
|
||
|
||
# 百度智能小程序
|
||
npm run dev:swan
|
||
|
||
# 字节跳动小程序
|
||
npm run dev:tt
|
||
|
||
# QQ小程序
|
||
npm run dev:qq
|
||
|
||
# 京东小程序
|
||
npm run dev:jd
|
||
```
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### 项目配置
|
||
主要配置文件位于 `config/` 目录：
|
||
|
||
- `config/index.ts` - Taro主配置文件
|
||
- `config/dev.ts` - 开发环境配置
|
||
- `config/prod.ts` - 生产环境配置
|
||
- `config/env.ts` - 环境变量配置（新增）
|
||
- `config/app.ts` - 应用配置（API地址、租户ID等）
|
||
|
||
### 环境变量配置
|
||
项目支持多环境配置，在 `config/env.ts` 中管理：
|
||
|
||
```typescript
|
||
// 环境变量配置
|
||
export const ENV_CONFIG = {
|
||
development: {
|
||
API_BASE_URL: 'http://localhost:3000/api',
|
||
APP_NAME: 'Taro App Dev',
|
||
DEBUG: 'true',
|
||
},
|
||
production: {
|
||
API_BASE_URL: 'https://api.example.com',
|
||
APP_NAME: 'Taro App',
|
||
DEBUG: 'false',
|
||
},
|
||
test: {
|
||
API_BASE_URL: 'https://test-api.example.com',
|
||
APP_NAME: 'Taro App Test',
|
||
DEBUG: 'true',
|
||
}
|
||
}
|
||
|
||
// 获取当前环境配置
|
||
export function getEnvConfig() {
|
||
const env = process.env.NODE_ENV || 'development'
|
||
if (env === 'production') {
|
||
return ENV_CONFIG.production
|
||
} else if (env === 'test') {
|
||
return ENV_CONFIG.test
|
||
} else {
|
||
return ENV_CONFIG.development
|
||
}
|
||
}
|
||
|
||
// 导出环境变量
|
||
export const { API_BASE_URL, APP_NAME, DEBUG } = getEnvConfig()
|
||
```
|
||
|
||
### 应用配置
|
||
在 `config/app.ts` 中配置：
|
||
```typescript
|
||
import { API_BASE_URL } from './env'
|
||
|
||
// 租户ID
|
||
export const TenantId = 'your_tenant_id'
|
||
|
||
// API基础地址（自动从环境配置读取）
|
||
export const BaseUrl = API_BASE_URL
|
||
|
||
// 其他配置...
|
||
```
|
||
|
||
### 环境切换
|
||
通过设置 `NODE_ENV` 环境变量来切换不同环境：
|
||
|
||
```bash
|
||
# 开发环境（默认）
|
||
npm run dev:weapp
|
||
|
||
# 生产环境
|
||
NODE_ENV=production npm run dev:weapp
|
||
|
||
# 测试环境
|
||
NODE_ENV=test npm run dev:weapp
|
||
```
|
||
|
||
## 🌍 环境变量详细说明
|
||
|
||
### 环境变量文件结构
|
||
```
|
||
config/
|
||
├── env.ts # 环境变量配置文件
|
||
├── app.ts # 应用配置（使用环境变量）
|
||
└── index.ts # Taro配置（注入环境变量）
|
||
```
|
||
|
||
### 支持的环境变量
|
||
| 变量名 | 说明 | 开发环境默认值 | 生产环境建议值 |
|
||
|--------|------|---------------|---------------|
|
||
| `API_BASE_URL` | API基础地址 | `http://localhost:3000/api` | `https://api.yourdomain.com/api` |
|
||
| `APP_NAME` | 应用名称 | `Taro App Dev` | `Your App Name` |
|
||
| `DEBUG` | 调试模式 | `true` | `false` |
|
||
|
||
### 环境变量使用方法
|
||
|
||
#### 1. 修改环境配置
|
||
编辑 `config/env.ts` 文件：
|
||
```typescript
|
||
export const ENV_CONFIG = {
|
||
development: {
|
||
API_BASE_URL: 'http://localhost:3000/api', // 修改为你的开发环境API地址
|
||
APP_NAME: 'My App Dev',
|
||
DEBUG: 'true',
|
||
},
|
||
production: {
|
||
API_BASE_URL: 'https://api.yourdomain.com/api', // 修改为你的生产环境API地址
|
||
APP_NAME: 'My App',
|
||
DEBUG: 'false',
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. 在代码中使用环境变量
|
||
```typescript
|
||
// 在 config/app.ts 中
|
||
import { API_BASE_URL, APP_NAME, DEBUG } from './env'
|
||
|
||
export const BaseUrl = API_BASE_URL
|
||
export const AppName = APP_NAME
|
||
export const IsDebug = DEBUG === 'true'
|
||
|
||
// 在其他文件中使用
|
||
import { BaseUrl } from '@/config/app'
|
||
console.log('API地址:', BaseUrl)
|
||
```
|
||
|
||
#### 3. 运行时环境切换
|
||
```bash
|
||
# 开发环境（默认）
|
||
npm run dev:weapp
|
||
|
||
# 生产环境
|
||
NODE_ENV=production npm run dev:weapp
|
||
|
||
# 测试环境
|
||
NODE_ENV=test npm run dev:weapp
|
||
|
||
# 构建生产版本
|
||
NODE_ENV=production npm run build:weapp
|
||
```
|
||
|
||
### 环境变量最佳实践
|
||
|
||
1. **敏感信息处理**：不要在代码中硬编码敏感信息，使用环境变量管理
|
||
2. **环境隔离**：确保不同环境使用不同的API地址和配置
|
||
3. **默认值设置**：为所有环境变量提供合理的默认值
|
||
4. **类型安全**：使用TypeScript确保环境变量的类型安全
|
||
|
||
### 路径别名配置
|
||
项目已配置路径别名，可以使用以下方式导入：
|
||
```typescript
|
||
import Component from '@/components/Component'
|
||
import { request } from '@/utils/request'
|
||
import { useCart } from '@/hooks/useCart'
|
||
import config from '@/config/app'
|
||
```
|
||
|
||
### 样式配置
|
||
- **Sass**: 支持嵌套、变量、混入等特性
|
||
- **TailwindCSS**: 原子化CSS，配置文件为 `tailwind.config.js`
|
||
- **PostCSS**: 自动处理CSS兼容性，配置文件为 `postcss.config.js`
|
||
|
||
## 🎯 核心功能
|
||
|
||
### 🔐 用户认证与授权
|
||
- **微信登录**：基于微信OpenID的用户认证
|
||
- **短信登录**：支持手机号短信验证登录
|
||
- **用户注册**：完整的用户注册流程
|
||
- **密码找回**：支持手机号找回密码
|
||
|
||
### 📝 内容管理系统(CMS)
|
||
- **文章浏览**：支持文章列表和详情查看
|
||
- **分类管理**：内容分类浏览
|
||
- **富文本渲染**：支持Markdown内容渲染
|
||
- **媒体展示**：图片、视频等媒体文件展示
|
||
|
||
### 🛒 电商系统
|
||
- **商品展示**：商品列表、详情、分类浏览
|
||
- **购物车**：商品加入购物车、数量管理
|
||
- **订单管理**：订单创建、查看、状态跟踪
|
||
- **地址管理**：收货地址的增删改查
|
||
- **支付集成**：支持微信支付等支付方式
|
||
|
||
### 👤 用户中心
|
||
- **个人资料**：用户信息查看和编辑
|
||
- **实名认证**：用户身份验证功能
|
||
- **帮助中心**：常见问题和帮助文档
|
||
- **关于我们**：应用介绍和联系方式
|
||
- **设置中心**：个人偏好设置
|
||
|
||
### 📊 数据可视化
|
||
- **图表展示**：基于ECharts的数据可视化
|
||
- **统计分析**：业务数据统计展示
|
||
- **实时更新**：动态数据更新
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
src/
|
||
├── app.config.ts # 应用配置文件
|
||
├── app.scss # 全局样式
|
||
├── app.ts # 应用入口文件
|
||
├── api/ # API接口定义
|
||
│ ├── cms/ # 内容管理相关API
|
||
│ ├── shop/ # 商城相关API
|
||
│ ├── system/ # 系统相关API
|
||
│ ├── passport/ # 用户认证相关API
|
||
│ └── index.ts # API统一导出
|
||
├── assets/ # 静态资源
|
||
│ └── tabbar/ # 底部导航图标
|
||
├── components/ # 公共组件
|
||
│ ├── Header.tsx # 页面头部组件
|
||
│ ├── TabBar.tsx # 底部导航组件
|
||
│ ├── GoodsList.tsx # 商品列表组件
|
||
│ └── ...
|
||
├── hooks/ # 自定义Hooks
|
||
│ └── useCart.ts # 购物车Hook
|
||
├── pages/ # 页面文件
|
||
│ ├── index/ # 首页
|
||
│ ├── cart/ # 购物车页面
|
||
│ ├── order/ # 订单页面
|
||
│ └── user/ # 用户中心页面
|
||
├── passport/ # 用户认证页面
|
||
│ ├── login.tsx # 登录页面
|
||
│ ├── register.tsx # 注册页面
|
||
│ └── ...
|
||
├── cms/ # 内容管理页面
|
||
│ ├── category/ # 分类页面
|
||
│ └── detail/ # 详情页面
|
||
├── shop/ # 商城页面
|
||
│ ├── category/ # 商品分类
|
||
│ ├── goodsDetail/ # 商品详情
|
||
│ ├── orderConfirm/ # 订单确认
|
||
│ └── orderDetail/ # 订单详情
|
||
├── user/ # 用户相关页面
|
||
│ ├── profile/ # 个人资料
|
||
│ ├── address/ # 地址管理
|
||
│ ├── setting/ # 设置
|
||
│ └── ...
|
||
└── utils/ # 工具函数
|
||
├── request.ts # 网络请求封装
|
||
├── common.ts # 通用工具函数
|
||
├── time.ts # 时间处理工具
|
||
└── server.ts # 服务端相关工具
|
||
|
||
config/ # 配置文件目录
|
||
├── index.ts # Taro主配置
|
||
├── dev.ts # 开发环境配置
|
||
├── prod.ts # 生产环境配置
|
||
├── env.ts # 环境变量配置
|
||
└── app.ts # 应用配置
|
||
|
||
types/ # 类型定义
|
||
└── global.d.ts # 全局类型定义
|
||
```
|
||
|
||
## 🔧 开发规范
|
||
|
||
### 代码结构
|
||
- **Pages**：页面组件，负责页面逻辑和UI展示
|
||
- **Components**：公共组件，可复用的UI组件
|
||
- **Hooks**：自定义Hooks，封装业务逻辑
|
||
- **Utils**：工具函数，通用的功能函数
|
||
- **API**：接口定义，与后端API的交互
|
||
|
||
### 命名规范
|
||
- **组件名**：使用大驼峰命名法（PascalCase）
|
||
- **文件名**：使用小驼峰命名法（camelCase）或短横线命名法（kebab-case）
|
||
- **变量名**：使用小驼峰命名法（camelCase）
|
||
- **常量**：使用全大写，下划线分隔
|
||
- **CSS类名**：使用短横线命名法（kebab-case）
|
||
|
||
### TypeScript规范
|
||
- 优先使用接口（interface）定义类型
|
||
- 为函数参数和返回值添加类型注解
|
||
- 使用泛型提高代码复用性
|
||
- 避免使用 `any` 类型
|
||
|
||
## 📚 构建与部署
|
||
|
||
### 构建命令
|
||
```bash
|
||
# 构建微信小程序
|
||
npm run build:weapp
|
||
|
||
# 构建H5应用
|
||
npm run build:h5
|
||
|
||
# 构建支付宝小程序
|
||
npm run build:alipay
|
||
|
||
# 构建其他平台
|
||
npm run build:swan # 百度智能小程序
|
||
npm run build:tt # 字节跳动小程序
|
||
npm run build:qq # QQ小程序
|
||
npm run build:jd # 京东小程序
|
||
```
|
||
|
||
### 主要API模块
|
||
项目API按功能模块组织：
|
||
|
||
- **用户认证**: `src/api/passport/` - 登录、注册、权限验证
|
||
- **用户管理**: `src/api/system/user/` - 用户信息管理
|
||
- **内容管理**: `src/api/cms/` - 文章、媒体文件管理
|
||
- **商城管理**: `src/api/shop/` - 商品、订单管理
|
||
- **系统管理**: `src/api/system/` - 系统配置、参数管理
|
||
|
||
## 🚀 部署指南
|
||
|
||
### 微信小程序部署
|
||
1. 构建小程序代码：
|
||
```bash
|
||
npm run build:weapp
|
||
```
|
||
2. 使用微信开发者工具打开 `dist` 目录
|
||
3. 点击"上传"按钮，上传代码到微信后台
|
||
4. 在微信公众平台提交审核
|
||
|
||
### H5应用部署
|
||
1. 构建H5应用：
|
||
```bash
|
||
npm run build:h5
|
||
```
|
||
2. 将 `dist` 目录下的文件上传到Web服务器
|
||
3. 配置Nginx或Apache服务器
|
||
4. 确保HTTPS访问（微信要求）
|
||
|
||
### 其他平台部署
|
||
各平台部署流程类似，构建对应平台代码后，使用相应的开发者工具上传即可。
|
||
|
||
### 生产环境配置
|
||
在生产环境中，需要修改相关配置：
|
||
|
||
1. **环境变量配置**：修改 `config/env.ts` 中的生产环境配置
|
||
```typescript
|
||
production: {
|
||
API_BASE_URL: 'https://your-production-api.com/api',
|
||
APP_NAME: 'Your App Name',
|
||
DEBUG: 'false',
|
||
}
|
||
```
|
||
|
||
2. **构建配置**：修改 `config/prod.ts` 中的构建配置
|
||
- 启用代码压缩和混淆
|
||
- 配置CDN加速
|
||
- 优化资源加载
|
||
|
||
3. **部署命令**：
|
||
```bash
|
||
NODE_ENV=production npm run build:weapp
|
||
```
|
||
|
||
## 🔧 常见问题
|
||
|
||
### 开发环境问题
|
||
1. **Node.js版本问题**：确保使用Node.js 16+版本
|
||
2. **依赖安装失败**：尝试清除缓存后重新安装
|
||
```bash
|
||
npm cache clean --force
|
||
npm install
|
||
```
|
||
3. **编译错误**：检查TypeScript配置和代码语法
|
||
|
||
### 小程序开发问题
|
||
1. **微信开发者工具无法预览**：检查appid配置和网络连接
|
||
2. **API请求失败**：确认后端服务正常运行，检查域名白名单
|
||
3. **样式显示异常**：检查rpx单位使用和NutUI组件样式
|
||
|
||
### 性能优化建议
|
||
1. **代码分割**：使用Taro的分包功能减少主包大小
|
||
2. **图片优化**：使用WebP格式，启用图片懒加载
|
||
3. **请求优化**：合并API请求，使用缓存机制
|
||
|
||
## 🤝 贡献指南
|
||
|
||
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) 文件了解详情
|
||
|
||
## 📞 联系我们
|
||
|
||
- 官网：https://websoft.top
|
||
- 邮箱：170083662@qq.com
|
||
- QQ群：479713884
|
||
|
||
---
|
||
|
||
⭐ 如果这个项目对您有帮助，请给我们一个星标！
|