taro-weapp-scaffold

基于 Taro 4 + React 18 + TypeScript 的微信小程序脚手架，内置完整的登录体系、国密（SM2/SM4）加密方案、TabBar 骨架与通用组件库。

技术栈

| 包 | 版本 | 用途 | |---|---|---| | @tarojs/taro | ^4.0.0 | 多端框架（本项目仅用微信小程序端） | | react | ^18.3.1 | UI（锁定 18，勿升 19） | | typescript | ^5.0.0 | 类型系统 | | recoil + recoil-nexus | ^0.7.6 | 全局状态管理 | | @nutui/nutui-react-taro | ^3.0.18 | UI 组件库 | | sm-crypto | ^0.3.13 | SM2/SM4 国密加密 | | dayjs | ^1.11.6 | 时间处理 |

目录结构

taro-weapp-scaffold/
├── config/
│   ├── index.js             # Taro 主构建配置（webpack5、CSS Modules、别名）
│   ├── dev.js               # 开发环境变量
│   ├── pre.js               # 预发布环境变量
│   ├── prod.js              # 生产环境变量
│   └── buffer-loader.js     # 大文件 Buffer 处理 loader
├── types/
│   └── global.d.ts          # 全局类型声明（图片、scss、sm-crypto）
├── src/
│   ├── app.tsx              # 根组件：Recoil 初始化、登录态守卫、用户信息刷新
│   ├── app.config.ts        # 页面路由注册 + TabBar 配置
│   ├── app.scss             # 全局基础样式
│   ├── store/
│   │   └── index.ts         # Recoil 原子：accessToken、userInfo、isLogin、effectiveToken
│   ├── utils/
│   │   ├── encrypt.ts       # SM2 字段加密 / SM4 请求体加解密 / 敏感字段解密
│   │   ├── request.ts       # HTTP 封装：Bearer token、响应体自动解密、401/30007 处理
│   │   ├── login.ts         # 登录工具：setToken、loginHandle（含 switchTab 判断）、resetLoginInfo
│   │   └── index.ts         # 通用工具：formatTime、formatName、navigateToWebView 等
│   ├── services/
│   │   ├── types.ts         # 通用分页类型
│   │   └── user.ts          # 登录 / 用户信息 / 退出 API
│   ├── hooks/
│   │   ├── useRequest.ts    # 异步请求 Hook（loading / data / error / run / refresh）
│   │   └── useParams.ts     # 类型安全的路由参数 Hook
│   ├── styles/
│   │   └── common.module.scss  # 公共样式：card、menuItem、ellipsis、safeBottom 等
│   ├── components/
│   │   ├── index.ts         # 组件统一导出
│   │   ├── NavBar/          # 自定义导航栏（状态栏高度自适应，返回 + 右侧插槽）
│   │   ├── EmptyState/      # 空态占位组件（icon + 文字）
│   │   └── LoadingView/     # 加载态（fullscreen 页面级 / inline 局部）
│   └── pages/
│       ├── login/           # 微信一键手机号登录 + 协议勾选
│       ├── profile-setup/   # 新用户头像 / 昵称完善（含头像上传）
│       ├── agreement/       # 用户协议 / 隐私政策展示页
│       ├── home/            # 首页（Tab 1）：示例模板，演示下拉刷新 + 空态
│       ├── profile/         # 我的（Tab 2）：用户信息卡 + 菜单 + 退出登录
│       └── webview/         # 内嵌 WebView 容器，配合 navigateToWebView() 使用
├── .eslintrc.js             # ESLint 配置（基于 eslint-config-taro/react）
├── .gitignore
├── babel.config.js
├── package.json
├── project.config.json      # 微信开发者工具配置
└── tsconfig.json

快速开始

1. 安装依赖

# 必须加 --legacy-peer-deps，否则 peer 依赖冲突
npm install --legacy-peer-deps

2. 配置环境变量

编辑 config/dev.js、config/pre.js、config/prod.js，填入实际值：

module.exports = {
  env: {
    PROXYURL: '"https://your-api-host.com/app"',    // 后端接口地址
    API_CRYPTO_SM4_KEY: '"your-16-byte-sm4-key"',   // SM4 请求体加密密钥（16字节）
    API_SENSITIVE_SM4_KEY: '"your-sensitive-key"',  // SM4 敏感字段解密密钥
  },
}

3. 配置小程序 AppID

编辑 project.config.json，替换 appid 字段：

{ "appid": "wx你的AppID" }

4. 配置 SM2 公钥

编辑 src/utils/encrypt.ts，替换 SM2_PUBLIC_KEY（十六进制，04 开头的未压缩格式）。

5. 放置 TabBar 图标

将 PNG 图标放入 src/assets/tabbar/，然后在 src/app.config.ts 中取消注释：

iconPath: 'assets/tabbar/home.png',
selectedIconPath: 'assets/tabbar/home-active.png',

6. 开发调试

npm run dev:weapp   # 微信小程序，监听模式
npm run dev:h5      # H5

用微信开发者工具打开 dist/weapp 目录。

登录流程

用户点击「微信登录」
  ↓ Taro.login() → loginCode
  ↓ openType="getPhoneNumber" → phoneCode
  ↓ POST /app/auth/wechat-login → { token, ...profile }
  ↓ setToken() 写入 Recoil + localStorage
  ↓ 新用户（newUser=true）→ /pages/profile-setup?from=login
  ↓ 有 nextRouteUrl → switchTab 或 redirectTo 目标页
  ↓ 默认 → switchTab /pages/home/index

守卫机制：app.tsx 在每次 App 回到前台时检查 localStorage，token 已清除则 reLaunch 到登录页。

加密方案

| 类型 | 算法 | 密钥来源 | 用途 | |---|---|---|---| | 请求体加密 | SM4（ECB）| API_CRYPTO_SM4_KEY | 接口请求体整体加密，Base64 传输 | | 响应体解密 | SM4 | API_CRYPTO_SM4_KEY | dataType=10 时自动解密，在 request.ts 拦截器处理 | | 敏感字段解密 | SM4 | API_SENSITIVE_SM4_KEY | 手机号、姓名等敏感字段，独立密钥 | | 字段级加密 | SM2 | SM2_PUBLIC_KEY（前端公钥）| 上报身份证号等高敏感字段 |

通用组件使用

import { NavBar, EmptyState, LoadingView } from '@/components'

// 自定义导航栏（需页面 config 设置 navigationStyle: 'custom'）
<NavBar title="页面标题" right={<Text>操作</Text>} />

// 列表空态
{list.length === 0 && !loading && <EmptyState text="暂无内容" />}

// 页面级加载
if (loading) return <LoadingView />

// 局部加载
{loadingMore && <LoadingView mode="inline" text="加载更多..." />}

公共样式使用

import commonStyles from '@/styles/common.module.scss'

// 卡片
<View className={commonStyles.card}>...</View>

// 菜单行
<View className={commonStyles.menuItem}>
  <Text className={commonStyles.menuItemLabel}>设置</Text>
  <Text className={commonStyles.menuItemArrow}>›</Text>
</View>

// 单行/多行省略
<Text className={commonStyles.ellipsis2}>长文本内容...</Text>

新增页面流程

1. 在 src/pages/[name]/ 下创建 index.tsx、index.config.ts、index.module.scss
2. 在 src/app.config.ts 的 pages 数组中注册路由
3. 若为 TabBar 页：同步更新 app.config.ts 的 tabBar.list 和 src/utils/login.ts 中的 TAB_PAGES 集合

接入新项目检查清单

• [ ] 替换 project.config.json 中的 appid
• [ ] 填写 config/*.js 中的接口地址和 SM4 密钥
• [ ] 替换 src/utils/encrypt.ts 中的 SM2_PUBLIC_KEY
• [ ] 修改 src/app.config.ts 中的 navigationBarTitleText（应用名称）
• [ ] 在 src/pages/login/index.tsx 中替换应用名称、Slogan
• [ ] 在 src/pages/agreement/ 中填写实际协议内容
• [ ] 将 TabBar PNG 图标放入 src/assets/tabbar/ 并取消 app.config.ts 中的注释
• [ ] 删除 src/pages/home/ 模板内容，替换为实际业务首页
• [ ] 根据实际接口路径调整 src/services/user.ts 中的 URL
• [ ] 若 TabBar 页面有变化，同步维护 src/utils/login.ts 中的 TAB_PAGES