README.md



manulife-weapp

基于 Taro 4 + Vue 3 + NutUI 的微信小程序模板项目


🚀 快速开始


安装依赖

pnpm install


开发模式

# 微信小程序
pnpm dev:weapp

# H5
pnpm dev:h5

# 支付宝小程序
pnpm dev:alipay


生产构建

pnpm build:weapp


📁 项目结构

src/
├── api/                    # API 接口层
│   ├── index.js           # 业务接口定义（需根据业务修改）
│   ├── fn.js              # HTTP 请求封装
│   └── wx/                # 微信相关接口（可选）
├── assets/                 # 静态资源
│   ├── images/            # 图片资源
│   ├── styles/            # 全局样式
│   └── css/               # CSS 文件
├── components/             # 通用组件
│   ├── PosterBuilder/     # 海报生成器（可选）
│   ├── time-picker-data/  # 时间选择器
│   ├── indexNav.vue       # 底部导航
│   └── qrCode.vue         # 二维码组件（可选）
├── composables/            # Composition API hooks
│   ├── useOfflineBookingCache.js        # 离线缓存 hook
│   └── useOfflineBookingCachePolling.js # 轮询刷新 hook
├── hooks/                  # 自定义 hooks
│   └── useGo.js           # 导航辅助 hook
├── pages/                  # 页面组件
│   ├── index/             # 首页（示例页面）
│   └── auth/              # 认证页（必须保留）
├── stores/                 # Pinia 状态管理
│   ├── router.js          # 路由状态（用于认证回跳）
│   ├── main.js            # 主 store
│   ├── host.js            # 配置 store
│   └── counter.js         # 示例 store
├── utils/                  # 工具函数
│   ├── authRedirect.js    # 认证流程核心（必须）
│   ├── request.js         # HTTP 客户端核心（必须）
│   ├── network.js         # 网络状态监测
│   ├── config.js          # 环境配置（⚠️ 需修改）
│   ├── tools.js           # 通用工具
│   ├── uiText.js          # 文案管理
│   ├── wechatPay.js       # 微信支付（可选）
│   ├── mixin.js           # Vue mixin
│   ├── polyfill.js        # 浏览器兼容
│   └── weapp.js           # 小程序工具
├── app.js                  # 应用入口
├── app.config.js           # 页面路由配置
└── app.less                # 全局样式


⚙️ 配置说明


1. 修改服务器配置

编辑 src/utils/config.js：

const BASE_URL = process.env.NODE_ENV === 'production'
    ? 'https://your-production-domain.com'  // 生产环境域名
    : 'https://your-dev-domain.com'         // 开发环境域名

export const REQUEST_DEFAULT_PARAMS = {
    f: 'YOUR_MODULE',           // 业务模块标识
    client_name: 'YOUR_APP',    // 应用名称
}


2. 定义 API 接口

编辑 src/api/index.js，添加您的业务接口：

import { buildApiUrl } from '@/utils/tools'

export const yourAPI = (params) => {
    return buildApiUrl('your_action', params)
}


3. 配置页面路由

编辑 src/app.config.js，添加您的页面：

export default {
  pages: [
    'pages/index/index',
    'pages/auth/index',
    'pages/your-page/index',  // 添加您的页面
  ],
  // ...
}


4. 双设计宽度体系

项目采用双设计宽度体系：


NutUI 组件：基准宽度 375px

其他所有页面：基准宽度 750px


此配置已在 config/index.js 中设置，请确保遵循此规范。


🔐 认证流程

项目内置完整的微信登录认证系统：


静默认证：应用启动时自动执行静默认证

401 自动刷新：当接口返回 401 时，自动刷新会话并重试请求

授权页回跳：认证完成后自动跳转回原页面


核心文件：


src/utils/authRedirect.js - 认证流程管理

src/utils/request.js - HTTP 请求拦截器


重要：后端需提供 /srv/?a=openid_wxapp 接口用于微信登录。


🌐 弱网/离线支持

项目内置弱网和离线支持：


请求超时处理：自动检测网络超时并降级处理

离线缓存：支持离线数据缓存和读取

弱网提示：统一的弱网提示文案


相关文件：


src/composables/useOfflineBookingCache.js
src/composables/useOfflineBookingCachePolling.js
src/utils/uiText.js


📦 技术栈


框架：Taro 4.x

UI 库：Vue 3 + NutUI 4.x

状态管理：Pinia

HTTP：axios-miniprogram

样式：Less + TailwindCSS

构建工具：Webpack 5


🎯 路径别名

已配置的路径别名：

@/utils      -> src/utils
@/components -> src/components
@/images     -> src/assets/images
@/assets     -> src/assets
@/composables-> src/composables
@/api        -> src/api
@/stores     -> src/stores
@/hooks      -> src/hooks


📝 开发规范


组件编写


使用 Vue 3 Composition API
组件统一放在 src/components/ 目录
Props 定义清晰，注释详细


API 调用


接口统一在 src/api/index.js 定义
使用 xxxAPI(params) 命名格式
请求方法统一使用 src/api/fn.js 中的封装


状态管理


使用 Pinia 进行状态管理
Store 文件统一放在 src/stores/ 目录
复杂逻辑使用 composables 封装


样式编写


通用样式使用 TailwindCSS 工具类
组件样式使用 Less
NutUI 组件使用 375px 设计稿，其他使用 750px


🔧 可选功能

以下功能可以根据项目需求选择使用或移除：


二维码组件：src/components/qrCode.vue


海报生成器：src/components/PosterBuilder/


微信支付：src/utils/wechatPay.js、src/api/wx/


时间选择器：src/components/time-picker-data/


离线缓存：src/composables/useOfflineBookingCache.js


📚 相关文档


Taro 官方文档
NutUI 文档
Vue 3 文档
Pinia 文档


⚠️ 注意事项


小程序启动会自动执行静默认证，确保后端接口正常
请求超时默认 5 秒，可在 src/utils/request.js 中修改
NutUI 组件已配置自动导入，无需手动引入
TailwindCSS 已禁用 preflight，避免与小程序样式冲突
认证失败会自动跳转到 /pages/auth/index


📄 License

MIT