yuantao/template-MP

Template

Fork 0

Files

yuantao 1621d79192 文档优化commit命令配置并新增AGENTS.md项目文档

2026-01-31 09:52:01 +08:00

14 KiB

Raw Blame History

项目概述 - IFLOW 上下文

这是一个基于 UniApp + Vue3 + uView-Plus 的微信小程序项目模板。它提供了一个基础的项目结构和一些常用的工具函数，方便快速开发微信小程序。

技术栈

UniApp: 跨平台开发框架，用于构建微信小程序。
Vue3: 渐进式 JavaScript 框架，用于构建用户界面。
uView-Plus: 基于 UniApp 的 UI 组件库。
z-paging: 高性能分页加载组件库
Vuex: 状态管理库，用于统一管理应用状态。
Vite: 现代化构建工具，配置了自定义插件用于manifest.json的appid替换。
luch-request: 网络请求库，提供请求封装和拦截器功能。
uniapp-error-monitor: 错误监控库，用于捕获和上报小程序运行时错误
dayjs: 轻量级日期时间处理库

目录结构

.
├── api/                   # 接口相关
│   ├── modules/           # 业务接口模块
│   └── request.js         # 请求封装和拦截器配置
├── common/                # 公共资源
│   ├── styles/            # 全局样式
│   │   ├── common.css     # CodeFun原子类样式
│   │   └── base.scss      # 全局样式变量和 Mixins
│   └── utils/             # 工具函数
│       └── tool.js        # 常用工具函数
├── components/            # 全局公共组件
├── wxcomponents/          # 微信原生组件
│   └── painter/           # 海报绘制组件
├── uni_modules/           # uni-app 插件
│   └── z-paging/          # 分页组件库
├── lib/                   # 第三方库
│   └── luch-request/      # luch-request 网络请求库
├── uview-plus/            # uView-Plus 组件库
├── mixins/                # Vue 混入
│   └── global.js          # 全局混入
├── pages/                 # 主包页面
│   └── index/             # 首页
├── subPages/              # 分包页面
│   └── welcome/           # 欢迎页
├── static/                # 静态资源文件
│   └── assets/            # 静态图片资源
├── store/                 # 状态管理
│   └── index.js           # Vuex store 配置
├── scripts/               # 自动化脚本
│   └── upload-weapp.js    # 微信小程序自动化上传脚本
├── App.vue               # 应用入口
├── main.js               # 主入口文件
├── pages.json            # 页面配置
├── manifest.json         # 应用配置
├── uni.scss              # 全局样式变量
├── vite.config.js        # Vite 编译配置
├── .nvmdrc               # Node.js 版本要求
├── .env                  # 环境变量配置
├── .iflow/               # iFlow CLI 配置
├── package.json          # 项目依赖配置
└── uni.promisify.adaptor.js  # uni-app promise 适配器

开发环境与运行

环境要求

Node.js (版本信息在 .nvmdrc 文件中指定，当前为 24.0.1)
npm 或 yarn

当前依赖

{
  "dependencies": {
    "dayjs": "*",
    "dotenv": "^17.2.2",
    "uniapp-error-monitor": "*",
    "vue": "^3.5.21"
  }
}

安装依赖

npm install

运行项目

由于这是一个 UniApp 项目，通常需要使用 HBuilderX 或其他支持 UniApp 的 IDE 来运行和调试：

使用 HBuilderX 打开项目
选择"运行到小程序模拟器"或"运行到手机或模拟器"
选择微信开发者工具

构建项目

同样，构建项目也需要使用 HBuilderX 或相应的 CLI 工具。

自动化上传微信小程序

项目提供了自动化上传微信小程序的功能，可以快速将编译后的小程序上传到微信开发者平台。

使用前准备

配置微信开发者工具CLI路径

需要设置环境变量 WECHAT_CLI_PATH，指向微信开发者工具CLI的路径：
- Windows: C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat
- macOS: /Applications/wechatwebdevtools.app/Contents/MacOS/cli
或者在 scripts/upload-weapp.js 中修改 CONFIG.cliPath 的值。
编译项目

使用 HBuilderX 编译项目，生成微信小程序代码：
- 打开 HBuilderX
- 点击"发行" → "小程序-微信"
- 等待编译完成

使用方法

编译完成后，运行以下命令进行上传：

npm run upload:weapp

功能特性

自动化上传脚本会自动执行以下操作：

版本号自增
- 自动递增 manifest.json 中的 versionName（如 1.0.0 → 1.0.1）
- 自动递增 versionCode
生成上传备注
- 获取当前 git 分支名
- 获取最近 5 条 git 提交日志
- 将英文相对时间转换为中文格式（如 "3 weeks ago" → "3周前"）
- 每条日志前添加序号（1、2、3...）
更新配置文件
- 更新 manifest.json 中的版本号
上传到微信
- 调用微信开发者工具CLI上传编译后的小程序

上传描述格式

上传备注的格式示例：

[master] (1) 新增IDE配置文件 (yuantao, 3周前) | (2) 优化工具函数 (yuantao, 6周前) | (3) 修复bug (yuantao, 7周前)

注意事项

上传前必须先使用 HBuilderX 编译项目
确保项目是 git 仓库（用于获取日志）
确保微信开发者工具CLI路径配置正确
编译后的文件位于 unpackage/dist/build/mp-weixin 目录

代码规范与开发约定

样式规范

全局样式变量: uni.scss 提供了全局样式变量
全局样式文件: 位于 common/styles/ 目录
- common.css: CodeFun 原子类样式，用于快速布局
- base.scss: SCSS 变量、Mixins 和常用样式类生成器
样式规范: 遵循项目中已有的样式风格，统一使用原子类

JavaScript 规范

ES6+: 严格遵循 ES6+ 语法规范
函数式编程: 优先使用函数式编程范式
函数定义: 使用 function 关键字定义方法函数
响应式数据:
- 少于 4 个 ref 时直接使用 ref
- 超过 4 个时使用 reactive 进行封装
生命周期: 通过 @dcloudio/uni-app 按需导入，如：
```
import { onLoad, onShow, onHide } from '@dcloudio/uni-app'
```
页面的加载、挂载生命周期不要使用 onMounted，应该使用 onLoad
变量命名:
- 小驼峰命名法: userName, orderList
- 常量全大写: MAX_LENGTH, DEFAULT_VALUE
- 状态类变量: isLogin, isOpen, isLoading
- 事件方法: onClick, onSelect, onSubmit
注释规范: 变量和方法必须有注释说明和类型说明
异步处理: 所有 Promise 类方法使用 async/await 写法，避免 .then 嵌套
字符串拼接: 使用 ES6 模板语法 `string ${variable}`

静态资源

资源路径: 使用全局混入的 ASSETSURL 变量

使用方式:

// 在 template 中
<image :src="`${ASSETSURL}image.png`"/>

// 在 CSS 中
background-image: url($ASSETSURL + 'image.png')

// 在 JavaScript 中
const ASSETSURL = import.meta.env.VITE_ASSETSURL
const imageUrl = `${ASSETSURL}image.png`

工具函数 (tool.js)

common/utils/tool.js 提供完整的工具函数库：

提示与加载

alert(str, icon, duration): 文字轻提示
- icon: 0-无, 1-成功, 2-加载中
- duration: 提示时间（毫秒）
loading(title, mask): 显示加载状态
hideLoading(): 隐藏加载状态

页面跳转

navigateTo(url): 可返回跳转（导航到新页面）
redirectTo(url): 不可返回跳转（重定向到新页面）
reLaunch(url): 清除页面栈跳转（重新启动到新页面）
switchTab(url): 跳转到 TabBar 页面
navigateBack(delta, fallbackUrl): 返回上一页面或指定页面

本地存储

storage(key, value): 设置或获取本地存储
- 传入 value: 设置存储
- 不传 value: 读取存储
- key 为 '#': 清空所有存储
removeStorage(key): 移除本地存储项
getStorageInfo(): 获取存储信息

其他功能

copy(data): 复制文本到剪贴板
saveImageToPhotos(url): 保存图片到相册（自动处理权限）
requestPayment(paymentData): 发起微信支付
upload(filePath): 文件上传（自动添加 token）
loadFont(fontName): 动态加载字体（支持缓存）

网络请求

请求配置

请求库: 使用 lib/luch-request 库进行封装
全局配置: 在 api/request.js 中定义
- 基础 URL: 通过环境变量 VITE_BASE_URL 配置
- SSL 验证: 关闭（sslVerify: false）
- 请求拦截器: 处理通用逻辑（如添加 token）
- 响应拦截器: 处理错误提示、错误监控上报等

错误监控

错误监控库: 集成 uniapp-error-monitor
监控配置: 在 main.js 中初始化
- 启用全局错误捕获: enableGlobalError: true
- 启用 Promise 错误捕获: enablePromiseError: true
- 禁用 console.error 捕获: enableConsoleError: false
- 企业微信机器人通知: 通过 VITE_WEBHOOK 配置
错误上报: 在 api/request.js 的响应拦截器中自动上报 API 错误

状态管理 (Vuex)

状态管理库: 使用 Vuex 进行全局状态管理
配置文件: store/index.js
当前状态: 基础配置，包含空的 state、mutations、actions 和 getters
使用方式: 通过 createStore 创建 store 实例

组件库

uni_modules 目录中的组件无需导入直接可以进行使用。
组件库: 集成 uView-Plus 和 z-paging
uView-Plus: 通过 easycom 自动导入，无需手动 import

// 直接使用，无需import
<u-button>按钮</u-button>
<u-icon name="home" />

组件分类:
全局组件: 放在 components/ 目录
页面组件: 放在页面根目录的 components/ 目录
微信原生组件: 放在页面根目录的 wxcomponents/ 目录

分页功能

分页组件: 使用 z-paging 实现高性能分页
全局配置: 在 main.js 中配置 uni.$zp
- empty-view-text: 空数据提示文字（"空空如也~~"）
- refresher-enabled: 是否启用下拉刷新（true）