🚀 WebSoft 小程序

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

📖 项目简介

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
演示账号	请联系开发者获取演示账号
正式账号	立即注册
关注公众号

🛠️ 技术栈

核心框架

技术	版本	说明
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. 克隆项目

git clone https://github.com/websoft-top/mp-taro.git
cd mp-taro

2. 安装依赖

# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install

# 或使用 yarn
yarn install

3. 配置开发环境

环境变量配置

项目支持多环境配置，通过 config/env.ts 文件管理不同环境的配置：

// 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等信息：

export const TenantId = 'your_tenant_id'
export const BaseUrl = API_BASE_URL  // 自动从环境配置读取

4. 启动开发服务器

微信小程序开发

# 开发环境（默认）
npm run dev:weapp

# 生产环境
NODE_ENV=production npm run dev:weapp

# 测试环境
NODE_ENV=test npm run dev:weapp

然后使用微信开发者工具打开 dist 目录

H5开发

# 启动H5开发模式
npm run dev:h5

访问 http://localhost:10086 查看H5版本

其他平台

# 支付宝小程序
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 中管理：

// 环境变量配置
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 中配置：

import { API_BASE_URL } from './env'

// 租户ID
export const TenantId = 'your_tenant_id'

// API基础地址（自动从环境配置读取）
export const BaseUrl = API_BASE_URL

// 其他配置...

环境切换

通过设置 NODE_ENV 环境变量来切换不同环境：

# 开发环境（默认）
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 文件：

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. 在代码中使用环境变量

// 在 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. 运行时环境切换

# 开发环境（默认）
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确保环境变量的类型安全

路径别名配置

项目已配置路径别名，可以使用以下方式导入：

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 类型

📚 构建与部署

构建命令

# 构建微信小程序
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. 构建小程序代码：

   npm run build:weapp
   

2. 使用微信开发者工具打开 dist 目录
3. 点击"上传"按钮，上传代码到微信后台
4. 在微信公众平台提交审核

H5应用部署

1. 构建H5应用：

   npm run build:h5
   

2. 将 dist 目录下的文件上传到Web服务器
3. 配置Nginx或Apache服务器
4. 确保HTTPS访问（微信要求）

其他平台部署

各平台部署流程类似，构建对应平台代码后，使用相应的开发者工具上传即可。

生产环境配置

在生产环境中，需要修改相关配置：

1. 环境变量配置：修改 config/env.ts 中的生产环境配置

   production: {
     API_BASE_URL: 'https://your-production-api.com/api',
     APP_NAME: 'Your App Name',
     DEBUG: 'false',
   }
   

2. 构建配置：修改 config/prod.ts 中的构建配置

   • 启用代码压缩和混淆
   • 配置CDN加速
   • 优化资源加载

3. 部署命令：

   NODE_ENV=production npm run build:weapp
   

🔧 常见问题

开发环境问题

1. Node.js版本问题：确保使用Node.js 16+版本
2. 依赖安装失败：尝试清除缓存后重新安装

   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 文件了解详情

📞 联系我们

• 官网：https://websoft.top
• 邮箱：170083662@qq.com
• QQ群：479713884

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！