React H5 Template

React 18 + TypeScript + Vite + antd-mobile v5 + Zustand 移动端H5模版

在线预览

📱 扫码体验 或点击 在线预览

技术栈

技术	版本	说明
React	18.3.1	UI 框架
TypeScript	5.6.3	类型系统
Vite	5.4.8	构建工具
antd-mobile	5.38.1	移动端 UI 组件库（蚂蚁官方）
Zustand	4.5.5	状态管理
React Router	6.26.1	路由管理
Axios	1.7.7	HTTP 请求
Sass	1.79.4	CSS 预处理器

特性

• ✅ React 18 + TypeScript 全类型支持
• ✅ Vite 极速开发体验，支持 HMR
• ✅ antd-mobile v5 蚂蚁官方移动端组件库
• ✅ Zustand 轻量状态管理，支持持久化
• ✅ React Router v6 路由守卫 + 懒加载
• ✅ Axios 请求封装，自动取消重复请求
• ✅ vw 移动端适配，基于 375 设计稿
• ✅ 路由权限控制，登录拦截自动跳转
• ✅ TabBar 底部导航，自动显隐控制
• ✅ 错误边界处理，防止白屏崩溃
• ✅ 网络状态监听，断网自动提示
• ✅ 代码规范，ESLint + Prettier 预设

环境要求

工具	版本
Node.js	>=22.20.2
pnpm	>=11.23.0

快速开始

# 克隆项目
git clone <your-repo-url>
cd react-h5-antd-mobile-v5

# 安装依赖（推荐 pnpm）
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产环境
pnpm build

# 预览生产构建
pnpm preview

项目结构

├── public/                 # 静态资源
├── src/
│   ├── assets/            # 图片、字体等资源
│   ├── components/        # 公共组件
│   │   ├── Auth/         # 路由权限守卫
│   │   ├── ErrorBoundary/# 错误边界
│   │   └── Layout/       # 页面布局（含 TabBar）
│   ├── hooks/            # 自定义 Hooks
│   ├── pages/            # 页面组件
│   │   ├── Home/        # 首页
│   │   ├── Login/       # 登录页
│   │   ├── Profile/     # 个人中心
│   │   └── NotFound/    # 404 页面
│   ├── router/           # 路由配置
│   ├── services/         # API 请求封装
│   ├── stores/           # Zustand 状态管理
│   ├── styles/           # 全局样式
│   ├── types/            # TypeScript 类型定义
│   ├── utils/            # 工具函数
│   ├── App.tsx           # 根组件
│   └── main.tsx          # 入口文件
├── .env.development      # 开发环境变量
├── .env.production       # 生产环境变量
├── vite.config.ts        # Vite 配置
├── tsconfig.json         # TypeScript 配置
├── postcss.config.js     # PostCSS 配置（vw 适配）
└── package.json

核心模块说明

1. 状态管理（Zustand）

// 用户状态
import { useUserStore } from '@/stores'

const { token, userInfo, isLogin, setToken, logout } = useUserStore()

// 全局状态
import { useGlobalStore } from '@/stores'

const { theme, loading, showTabBar, setTheme } = useGlobalStore()

2. HTTP 请求封装

import { get, post } from '@/services'

// GET 请求
const data = await get('/api/list', { page: 1, pageSize: 10 })

// POST 请求
const result = await post('/api/submit', { name: 'test' })

特性：

• 自动携带 Token
• 自动取消重复请求
• 统一错误处理（401 自动跳转登录）
• 网络异常自动提示

3. 路由配置

// src/router/index.ts
{
  path: '/home',
  element: (
    <AuthGuard>
      <Home />
    </AuthGuard>
  ),
  handle: {
    meta: {
      title: '首页',
      requiresAuth: true,  // 需要登录
      tabBar: true         // 显示 TabBar
    }
  }
}

4. 移动端适配

基于 postcss-px-to-viewport 实现，设计稿宽度 375px：

// 写 px，自动转 vw
.container {
  width: 375px; // -> 100vw
  padding: 16px; // -> 4.267vw
}

注意：adm- 开头的 antd-mobile 类名已加入黑名单，不会转换。

环境变量

变量	开发环境	生产环境	说明
VITE_API_BASE_URL	/api	https://api.example.com	API 基础地址
VITE_APP_TITLE	React H5 Dev	React H5	应用标题

脚本命令

命令	说明
pnpm dev	启动开发服务器（端口 3000）
pnpm build	生产构建
pnpm build:test	测试环境构建
pnpm preview	预览生产构建
pnpm lint	ESLint 代码检查
pnpm lint:fix	ESLint 自动修复
pnpm format	Prettier 格式化
pnpm typecheck	TypeScript 类型检查

浏览器兼容

• iOS Safari >= 12
• Chrome >= 80
• 微信内置浏览器
• 企业微信内置浏览器

开源协议

MIT License

贡献

欢迎提交 Issue 和 PR！

---

如果这个项目对你有帮助，请给个 ⭐️ Star 支持一下！