更新记录

2.0.0（2026-06-05） 下载此版本

微信小程序和h5兼容打包

平台兼容性

uni-app

小程序模板

项目简介

本项目是基于 uni-app + Vue 3 + TypeScript 开发的小程序模板，采用 Vite 5.0+ 作为构建工具，Pinia 作为状态管理库，uview-plus 3.4+ 作为 UI 组件库。

技术栈

• 框架: Uniapp、Vue 3.4+
• 打包构建工具: Vite 5.0+
• 状态管理: Pinia
• UI 组件库: uview-plus 3.4+
• CSS 预处理器: Scss
• 代码校验与格式化: ESLint、Prettier
• 开发语言: TypeScript
• 包管理工具: pnpm

快速开始

项目设置

pnpm install

开发环境

pnpm dev:h5
pnpm dev:mp-weixin

测试环境

# 测试环境构建
pnpm build:h5:test
pnpm build:mp-weixin

生产环境运行

pnpm build:h5
pnpm build:mp-weixin

版本管理

• 测试版本号: 1.0.0.dev1
• 线上版本号: 1.0.0

环境配置

工程需配置

• Node.js 版本: node-22.22.22-x64.msi
• vite 版本: vite

部署配置

1. 版本设置:

   • 基础库最低可用版本: 3.10.3

2. 服务器域名:

   • request 合法域名
   • socket 合法域名
   • uploadFile 合法域名
   • downloadFile 合法域名
   • udp 合法域名
   • tcp 合法域名

3. 服务内容声明:

   • 用户隐私保护指引: 开发者将在获取你的明示同意后，收集你的手机号，用途是(注册、登录小程序)

4. 接口设置:

5. 扫普通链接二维码打开小程序:

6. 业务域名:

   • 可调用 web-view 组件

文档

• 开发者 ID：xx appId：xxx appSecret：xxx
• 接口文档：

测试环境

• 服务器: 待补充
• H5 部署路径: 待补充
• 接口地址: 待补充

生产环境

• 服务器: 待补充
• H5 部署路径: 待补充
• 接口地址: 待补充

目录结构

├─ .trae/
│  └─ rules/
│     └─ project_rules.md
├─ src/
│  ├─ api/                # 接口定义与请求封装
│  ├─ assets/             # 样式、字体、脚本等资源
│  ├─ components/         # 通用组件
│  ├─ config/             # 项目配置
│  ├─ hooks/              # 组合式函数
│  │  ├─ useClipboard/    # 剪贴板能力封装（复制文本等）
│  │  │  └─ index.ts
│  │  └─ usePermission/   # 权限相关能力封装（授权状态、权限处理）
│  │     └─ index.ts
│  ├─ lang/               # 国际化语言包
│  ├─ pages/              # 业务页面
│  ├─ pagesCommon/        # 通用页面（登录、404、webView 等）
│  ├─ plugins/            # 插件注册（如 uview）
│  ├─ router/             # 路由与权限控制
│  ├─ static/             # 静态资源（图片等）
│  ├─ store/              # Pinia 状态管理
│  │  ├─ modules/
│  │  └─ index.ts
│  ├─ utils/              # 工具方法与通用能力
│  │  ├─ auth/            # 鉴权相关工具（token、登录态校验等）
│  │  │  └─ index.ts
│  │  ├─ common/          # 通用工具函数（格式化、判空、基础能力）
│  │  │  └─ index.ts
│  │  ├─ dayjs/           # 时间处理封装
│  │  │  └─ index.ts
│  │  ├─ modals/          # 模态弹窗能力封装
│  │  │  ├─ index.ts
│  │  │  └─ types.ts
│  │  ├─ request/         # 网络请求封装（实例、拦截器、状态码、类型）
│  │  │  ├─ index.ts
│  │  │  ├─ interceptors.ts
│  │  │  ├─ status.ts
│  │  │  └─ types.ts
│  │  ├─ storage/         # 本地缓存封装（uni.setStorage 等）
│  │  │  └─ index.ts
│  │  ├─ validate/        # 表单与业务字段校验工具
│  │  │  └─ index.ts
│  │  └─ index.ts         # utils 统一导出入口
│  ├─ App.vue             # 应用入口组件
│  ├─ main.ts             # 应用启动入口
│  ├─ pages.json          # uni-app 页面路由配置
│  ├─ manifest.json       # uni-app 平台配置
│  └─ uni.scss            # 全局样式变量
├─ types/                 # 全局类型声明
├─ vite.config.ts         # Vite 配置
├─ tsconfig.json          # TypeScript 配置
├─ eslint.config.js       # ESLint 配置
├─ package.json           # 项目依赖与脚本
└─ pnpm-lock.yaml         # 依赖锁文件

• 保持目录结构清晰，遵循现有目录规范

开发规范

代码格式化

项目使用 ESLint + Prettier 进行代码格式化，配置如下：

{
  "printWidth": 160, // 换行字符串阈值
  "tabWidth": 2, // 设置工具每一个水平缩进的空格数
  "singleQuote": true, // 用单引号
  "semi": false, // 句末是否加分号
  "endOfLine": "auto", // 保持原有规则
  "trailingComma": "none", // 是否为多行数组的非末尾行添加逗号
  "bracketSameLine": false, // 是否将 > 放在多行元素的同一行
  "arrowParens": "always", // (x) => {} 是否要有小括号
  "htmlWhitespaceSensitivity": "ignore" // html结尾符合不换行
}

IDEA 快捷键设置

1. 搜索 ESLint 在 Keymap
2. 找到 Fix ESlint Problems 设置快捷键，推荐：Ctrl+Alt+L

页面统一结构

<template lang="html">
  <!-- header_start   -->
  <hxkHeader></hxkHeader>
  <!-- header_end   -->

  <!-- center_start -->
  <div class="pageContent pbCont container"></div>
  <!-- center_end -->

  <!-- 组件页面的引用在下面 -->
  <popupTitle :value="popupShow" :isHeader="true" @on-show="toPopupShow" @on-close="toPopupClose">
    <div style="height: 200px"></div>
  </popupTitle>
</template>

<script setup lang="ts">
/******************************* 全局变量 *******************************/

/******************************* 功能1 *******************************/

/******************************* 功能2 *******************************/
</script>

<style lang="scss" scoped></style>

常见问题

1. JS 获取图片资源

<img class="img" :src="proxy.$utils.getAssetsFile(`logo.png`)" />

2. 小程序组件无法使用 data- 定义 props

问题描述： 在小程序端，如果组件的 props 参数名以 data- 开头（如 data-list），会导致 props 参数无法正常接收和传递。

原因分析： 在小程序规范中，data- 默认被保留用于定义 dataset 自定义数据属性（例如 data-id 等用于事件传参），因此不能将该前缀用作组件的 props 定义。

解决方案： 定义组件 props 时，绝对不要使用 data- 作为前缀。建议使用其他命名方式，例如 itemList（在模板中为 :item-list）或者 listData 等。

注意事项

• 项目使用路径别名 @ 指向 src 目录
• 所有函数/方法必须添加 JSDoc 注释
• 优先使用组合式 API (Composition API) 并搭配 <script setup lang="ts"> 语法糖
• 使用 TypeScript 进行开发，避免使用 any 类型
• 优先使用 Scoped CSS
• 使用 v-for 时必须提供唯一的 key
• 不要在同一元素上同时使用 v-if 和 v-for