yuantao/template-MP

Template

Fork 0

Files

yuantao f593b3ff7c 文档更新项目文档，添加自动化上传功能说明

2026-01-19 11:52:37 +08:00

12 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: 网络请求库，提供请求封装和拦截器功能。

目录结构

.
├── api/                   # 接口相关
│   ├── modules/           # 业务接口（目录存在待完善）
│   └── request.js         # 请求封装
├── common/                # 公共资源
│   ├── styles/            # 全局样式
│   │   ├── common.css     # codefun原子类样式（预留）
│   │   └── base.scss      # 全局样式变量（预留）
│   └── 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/                 # 状态管理
├── 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中
background-image: url($ASSETSURL + 'image.png')

// 在JavaScript中
const imageUrl = `${ASSETSURL}image.png`

工具函数 (tool.js)

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

提示与加载

alert(): 文字轻提示
loading(): 显示加载状态
hideLoading(): 隐藏加载状态

页面跳转

navigateTo(): 跳转到指定页面
redirectTo(): 关闭当前页面并跳转
reLaunch(): 关闭所有页面并跳转
switchTab(): 跳转到TabBar页面
navigateBack(): 返回上一页面

本地存储

storage(): 设置或获取本地存储
removeStorage(): 移除本地存储项
getStorageInfo(): 获取存储信息

其他功能

copy(): 复制文本到剪贴板
saveImageToPhotos(): 保存图片到相册
requestPayment(): 发起微信支付
upload(): 文件上传
loadFont(): 动态加载字体

网络请求

网络请求使用 lib/luch-request 库进行封装。
全局配置在 api/request.js 中定义，包括基础URL、请求头、SSL验证等。
包含请求和响应拦截器，用于处理通用逻辑（如错误提示、鉴权等）。
基础URL通过环境变量 VITE_BASE_URL 配置。
各业务板块的接口都应存放在 api/modules 下，并将单个接口进行导出以便页面按需导入。

状态管理 (Vuex)

项目集成了Vuex进行全局状态管理。
状态管理文件位于 store/index.js。
使用 createStore 创建store实例。
目前处于基础状态，包含空的state、mutations、actions和getters。

组件规范

uni_modules 目录中的组件无需导入直接可以进行使用。
组件库: 集成 uView-Plus 和 z-paging

自动导入: uView-Plus 通过 easycom 自动导入

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

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

分页功能

分页组件: 使用 z-paging 实现高性能分页