更新记录

1.0.0（2024-11-26） 下载此版本

首次发布

平台兼容性

vue3-uniapp-template

简介

vue3-uniapp-template 是基于 vue3 的 uniapp 快速开发模板，包含状态管理、网络请求、路由拦截、UI组件、国际化、token 无感刷新、接口签名等常用功能。

主要使用的技术栈：uniapp、vue3、pinia、vite、vue-i18n、uv-ui 。

项目启动

# 克隆代码
git clone https://github.com/cshaptx4869/vue3-uniapp-template.git

# 切换目录
cd vue3-uniapp-template

# 安装依赖（使用pnpm也行，但在使用过程中发现一些奇葩的问题，比如安装某个包后引入使用时，会报某个依赖库找不到错误，也不清楚是不是HBuilderX的Bug）
npm install

# 启动HBuilderX运行项目

效果预览

目录结构

vue3-uniapp-template
├─ .commitlintrc.js
├─ .editorconfig
├─ .env.development                    // 运行环境变量
├─ .env.production                     // 发行环境变量
├─ .gitignore
├─ .lintstagedrc.js
├─ .prettierignore
├─ .prettierrc.js
├─ api                                 // api管理
│  ├─ index.js
│  └─ modules                          // api模块化
│     ├─ auth.js
│     └─ user.js
├─ App.vue
├─ components                          // 项目组件库
│  ├─ LangSelect                       // 语言切换组件
│  │  └─ LangSelect.vue
├─ hooks                               // hooks管理
│  └─ usePermission.js                 // 登录鉴权hook
├─ index.html
├─ LICENSE
├─ locale                              // 国际化管理
│  ├─ en.json
│  ├─ index.js
│  ├─ ja.json
│  ├─ uni-app.ja.json
│  ├─ zh-Hans.json
│  └─ zh-Hant.json
├─ main.js
├─ manifest.json
├─ package.json
├─ pages                               // 页面管理
│  ├─ 404
│  │  └─ 404.vue
│  ├─ index
│  │  └─ index.vue
│  ├─ login
│  │  └─ login.vue
│  └─ webview
│     └─ webview.vue
├─ pages.json                          // 页面路由
├─ pagesA                              // 分包A页面管理
│  └─ test
│     └─ test.vue
├─ plugins                             // 插件管理
│  ├─ index.js
│  ├─ permission.js                    // 路由拦截
│  └─ ui.js                            // UV-UI扩展配置
├─ README.md
├─ static                              // 静态资源管理
│  ├─ 404.png
│  └─ logo.png
├─ store                               // store管理
│  ├─ index.js
│  └─ modules                          // store模块化
│     ├─ auth.js
│     └─ user.js
├─ uni.scss
├─ utils                               // 工具管理
│  ├─ cache.js                         // 缓存
│  └─ request.js                       // 网络请求
└─ vite.config.js

这边提一嘴，uniapp 默认启用easycom 组件规范

• 只要组件安装在项目的 components 目录下或 uni_modules 目录下，并符合components/组件名称/组件名称.(vue|uvue)目录结构。就可以不用引用、注册，直接在页面中使用。
• 如果你的组件名称或路径不符合 easycom 的默认规范，可以在 pages.json 的 easycom 节点进行个性化设置，自定义匹配组件的策略。

登录鉴权

页面是否需要登录，只需在 pages.json 文件中需要鉴权的页面下设置 needLogin 为 true 即可，比如

{
  "pages": [
    {
      "path": "pages/test/test",
      "needLogin": true,
      "style": {
        "navigationBarTitleText": "",
      },
    }
  ]
}

注意：拦截 uni.switchTab 本身没有问题。但是在微信小程序端点击 tabbar 的底层逻辑并不是触发 uni.switchTab。所以误认为拦截无效，此类场景的解决方案是在 tabbar 页面的页面生命周期 onShow 中处理。

<template>
  <view class="container">
    <view>我是Tabbar页面</view>
  </view>
</template>

<script setup lang="ts">
// 引入鉴权hooks
import { usePermission } from "@/hooks/usePermission";
import { onShow } from "@dcloudio/uni-app";

onShow(async () => {
  console.log("tabbar page onShow");
  const hasPermission = await usePermission();
  console.log(hasPermission ? "已登录" : "未登录，拦截跳转");
  // 以下开始写业务逻辑...
});
</script>

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

网络请求

网络请求封装文件：utils/request.js 文件

• 默认未启用接口签名，可以修改 API_SAFE 为 true 启用，并建议修改 API_KEY 值。
• 默认未启用 refresh token，可以修改 ENABLED_REFRESH_TOKEN 为 true 启用。
• 根据实际业务情况修改 HeaderEnum、CodeEnum 中对应的内容。

注意事项

• 接口请求地址在根目录下的 .env.xxx 文件配置（development 为 “运行” 环境，production 为 “发行” 环境）
• 打开 uniapp 插件市场，搜索 Prettier，点击 “下载插件并导入HBuilderX” 安装插件，并配置 Prettier 插件

• 设置 HBuilderX 保存时自动格式化

• Git 提交使用 npm run commit 命令

• Web 端发行时慎选树摇优化，会有奇葩的问题... 比如 uv-ui 有的组件没有被打包进去😱

• 其他 HBuilderX 插件推荐：eslint-plugin-vue、eslint-js

移除所有示例代码

1. 移除 pagesA 目录
2. 移除 pages/demo 目录
3. 移除 pages.json 中无用路由以及 subPackages、preloadRule、tabBar
4. 移除 manifest.json 中 mp-weixin 下的 permission、requiredPrivateInfos 配置
5. 修改首页、登录页内容