🚀 WebSoft 小程序

基于 Taro + React + TypeScript 的跨平台小程序应用

Taro React TypeScript NutUI TailwindCSS License

## 📖 项目简介 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) | | 关注公众号 | ![输入图片说明](https://oss.wsdns.cn/20240327/f1175cc5aae741d3af05484747270bd5.jpeg?x-oss-process=image/resize,m_fixed,w_150/quality,Q_90) | ## 🛠️ 技术栈 ### 核心框架 | 技术 | 版本 | 说明 | |------|------|------| | 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 --- ⭐ 如果这个项目对您有帮助，请给我们一个星标！