uniapp+vue3+vite+ts+uview-plus 最完整最详细搭建项目步骤

目录

[一. 创建 uni-app 项目](#一. 创建 uni-app 项目)

[二. 编译和运行 uni-app 项目](#二. 编译和运行 uni-app 项目)

[三. TS 类型校验](#三. TS 类型校验)

[四. JSON 注释问题](#四. JSON 注释问题)

[五. 安装uview-plus ](#五. 安装uview-plus )

[ 六. 配置pinia持久化](# 六. 配置pinia持久化)

[七. 封装http请求 ](#七. 封装http请求 )

---

搭建项目的准备工作：

通过vue-cli脚手架 创建 uni-app 项目，便于更好的兼容TS写法

node版本：v18.16.0

pnpm版本：8.3.0

vscode安装uni-app 开发插件：

• uni-create-view ：快速创建 uni-app 页面；
• uni-helper ：uni-app 代码提示，其中包括5个小程序扩展包；

一. 创建 uni-app 项目

主要是通过vue-cli脚手架 创建 uni-app 项目，便于更好的兼容TS写法，使用Vue3/Vite版：

npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project

注意：

• Vue3/Vite版要求 node 版本^14.18.0 || >=16.0.0
• 如命令行创建失败，请直接访问 gitee 下载模板

更多的注意安装流程和注意事项可以参考官网：uni-app官网

二. 编译和运行 [uni-app 项目](https://so.csdn.net/so/search?q=uni-app 项目&spm=1001.2101.3001.7020)

1. 安装依赖 pnpm install

2. 运行项目 pnpm dev:mp-weixin

在运行项目时，可以打开package.json文件，在scripts配置中可以查看到运行项目的命令，如果是运行微信小程序，则通过pnpm dev:mp-weixin，打包则是pnpm build:mp-weixin，当然也可以自行配置快捷启动命名哦，如"serve": “pnpm dev:mp-weixin”；

运行完项目后，目录会生成dist文件夹，里面的dev中mp-weixin文件则是用于运行编译的文件；

3. 导入微信开发者工具

在运行项目完成后，按照提示运行方式：打开微信开发者工具, 导入 dist\dev\mp-weixin 运行，此时就可以在微信开发者工具成功运行并编译该项目；

三. TS 类型校验

打开项目结构，会发现tsconfig.json有报错提示：

Option 'importsNotUsedAsValues' is deprecated and will stop functioning in TypeScript 5.5. Specify compilerOption '"ignoreDeprecations": "5.0"' to silence this error.



  Use 'verbatimModuleSyntax' instead.ts

描述：警告消息与 TypeScript 编译器选项的弃用有关importsNotUsedAsValues，并建议改用该verbatimModuleSyntax选项。要在 TypeScript 5.5 之前使错误消息静音，您可以添加ignoreDeprecations": "5.0"到编译器选项；

解决：可以在tsconfig.json文件中"compilerOptions"配置项内添加"ignoreDeprecations": “5.0”

  "compilerOptions": {



    "ignoreDeprecations": "5.0"



  },

° 此时我们打开vue文件中，任意写一些组件，如：

<image mode="xxx"></image>

在image内置组件的mode属性中很显然是没有“xxx”的属性值，但是代码中并没有错误提示，所以为了符合Ts校验，我们需要额外配置Ts类型校验：

1. 安装类型声明文件：

pnpm i -D @types/wechat-miniprogram @uni-helper/uni-app-types

2. 配置tsconfig.json：

// tsconfig.json



{



  "extends": "@vue/tsconfig/tsconfig.json",



  "compilerOptions": {



    "ignoreDeprecations": "5.0",



    "sourceMap": true,



    "baseUrl": ".",



    "paths": {



      "@/*": ["./src/*"]



    },



    "lib": ["esnext","dom"],



    "types": [



      "@dcloudio/types", // uni-app API 类型



      "miniprogram-api-typings", // 原生微信小程序类型



      "@uni-helper/uni-app-types" // uni-app 组件类型



    ]



  },



  // vue 编译器类型，校验标签类型



  "vueCompilerOptions": {



    "nativeTags": ["block","component","template","slot"],



  },



  "include": ["src/**/*.ts","src/**/*.d.ts","src/**/*.tsx","src/**/*.vue"]



}

在配置完成后，刚才的vue组件就会提示报错信息，并且在image组件下方会有红色波浪线显示；

装类型声明文件类型声明文件

四. JSON 注释问题

在manifest.json和pages.json文件中，往往我们会添加一些注释信息，但是JSON规范不支持在文件中添加注释，会被视为无效的标记，并且会导致解析错误。

此时我们可以vscode工作区中进行配置：

在vscode面板中，点击右小角设置按钮→点击设置→在搜索设置中搜索“文件关联”→找到Files: Associations的配置项→点击添加项→把 manifest.json 和 pages.json 设置为 jsonc即可；

五. 安装uview-plus

我们使用的UI框架是uview-plus, uview-plus是基于uView2.0初步修改，支持vue3写法，组件也是很丰富的，这里会简单介绍一下安装以及配置的步骤，具体的详细步骤流程可以参考官网：uview-plus 3.0 - 全面兼容nvue的uni-app生态框架 - uni-app UI框架

1. 安装

pnpm add uview-plus



pnpm add dayjs



pnpm add clipboard

注意： 此安装方式必须要按照npm方式安装的配置中的说明配置了才可用，且项目名称不能有中文字符。

因为uview-plus依赖SCSS，所以必须要安装此插件，否则无法正常运行。

// 安装sass



pnpm add sass -D



 



// 安装sass-loader，注意需要版本10，否则可能会导致vue与sass的兼容问题而报错



pnpm add sass-loader@10 -D

2. 配置步骤

引入uview-plus主JS库：在项目src目录中的main.js中，引入并使用uview-plus的JS库，注意这两行要放在const app = createSSRApp(App)之后。

// main.js



import uviewPlus from 'uview-plus'



 



// #ifdef VUE3



import { createSSRApp } from 'vue'



export function createApp() {



  const app = createSSRApp(App)



  app.use(uviewPlus)



  return {



    app



  }



}



// #endif

引入uview-plus的全局SCSS主题文件： 在项目根目录的uni.scss中引入此文件。

/* uni.scss */



@import 'uview-plus/theme.scss';

引入uview-plus基础样式： 在App.vue中首行的位置引入，注意给style标签加入lang="scss"属性。

// App.vue



<style lang="scss">



	/* 注意要写在第一行，同时给style标签加入lang="scss"属性 */



	@import "uview-plus/index.scss";



</style>

配置easycom组件模式：需要在项目src目录的pages.json中进行。

// pages.json



{



	"easycom": {



		// 注意一定要放在custom里，否则无效，https://ask.dcloud.net.cn/question/131175



		"custom": {



			"^u--(.*)": "uview-plus/components/u-$1/u-$1.vue",



			"^up-(.*)": "uview-plus/components/u-$1/u-$1.vue",



	        "^u-([^-].*)": "uview-plus/components/u-$1/u-$1.vue"



		}



	},



	



	// 此为本身已有的内容



	"pages": [



		// ......



	]



}

注意：

在配置完后，可以发现在mian.ts中引入uview-plus时会提示ts报错：无法找到模块“uview-plus”的声明文件。

可以在src文件中创建一个types文件夹专门用来存放ts类型声明文件，在文件中新建uview.d.ts文件写入下方声明代码即可：

declare module "uview-plus"

3. 使用

下载和配置完成之后，在某个页面可以直接使用组件，无需通过import引入组件

<u-button text="提交"></u-button>

六. 配置pinia持久化

在vue3+vite中使用的状态管理库是pinia，官网：Pinia 中文文档

**1. 安装pinia:**使用 HBuilder X 不需要手动安装，直接使用即可。使用 CLI 需要手动安装:

pnpm add pinia@2.0.33

\2. 用法：

//main.js



 



import { createSSRApp } from 'vue';



import * as Pinia from 'pinia';



 



export function createApp() {



	const app = createSSRApp(App);



	app.use(Pinia.createPinia());



	return {



		app,



		Pinia, // 此处必须将 Pinia 返回



	};



}

创建创建一个 Store文件夹counter.ts

// stores/counter.js



import { defineStore } from 'pinia';



 



export const useCounterStore = defineStore('counter', {



	state: () => {



		return { count: 0 };



	},



	// 也可以这样定义



	// state: () => ({ count: 0 })



	actions: {



		increment() {



			this.count++;



		},



	},



});

在组件中使用它:

<script setup>



import { useCounterStore } from '@/stores/counter'



const counter = useCounterStore()



counter.count++



// 自动补全！ ✨



counter.$patch({ count: counter.count + 1 })



// 或使用 action 代替



counter.increment()



</script>



<template>



  <!-- 直接从 store 中访问 state -->



  <div>Current Count: {{ counter.count }}</div>



</template>

注意：pinia和vuex同样有个缺点刷新页面后数据是会丢失的，所以一般登录的token等信息既会保存到store中也会保存到本地存储等，从而实现持久化存储。

这里我们实现持久化存储用到了插件 快速开始 | pinia-plugin-persistedstate

1. 安装插件

pnpm i pinia-plugin-persistedstate

2. 将插件添加到 pinia 实例上

import { createPinia } from 'pinia'



import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'



 



const pinia = createPinia()



pinia.use(piniaPluginPersistedstate)

3. 用法

创建 Store 时，将 persist 选项设置为 true。

import { defineStore } from 'pinia'



 



export const useStore = defineStore(



  'main',



  () => {



    const someState = ref('你好 pinia')



    return { someState }



  },



  {



    persist: true,



  },



)

4. 多端兼容

export const useMemberStore = defineStore(



  'main',



  () => {



    //…省略



  },



  {



    // 配置持久化



    persist: {



      // 调整为兼容多端的API



      storage: {



        setItem(key, value) {



          uni.setStorageSync(key, value) 



        },



        getItem(key) {



          return uni.getStorageSync(key) 



        },



      },



    },



  },



)

七. 封装http请求

为了更方便的进行axios数据请求，可以将小程序的数据请求封装为Promise请求函数

1. 请求和上传文件拦截器

uniapp 拦截器： uni.addInterceptor

// src/utils/http.ts



 



// 请求基地址



const baseURL = 'xxxx'



 



// 拦截器配置



const httpInterceptor = {



  // 拦截前触发



  invoke(options: UniApp.RequestOptions) {



    // 1. 非 http 开头需拼接地址



    if (!options.url.startsWith('http')) {



      options.url = baseURL + options.url



    }



    // 2. 请求超时



    options.timeout = 10000



    // 3. 添加小程序端请求头标识



    options.header = {



      'source-client': 'miniapp',



      ...options.header,



    }



    // 4. 添加 token 请求头标识



    const memberStore = useMemberStore()



    const token = memberStore.profile?.token



    if (token) {



      options.header.Authorization = token



    }



  },



}



 



// 拦截 request 请求



uni.addInterceptor('request', httpInterceptor)



// 拦截 uploadFile 文件上传



uni.addInterceptor('uploadFile', httpInterceptor)

注意事项：微信小程序端，需登录微信公众平台配置合法域名；

2. 封装 Promise 请求函数

需求:返回 Promise 对象，用于处理返回值类型，成功通过resolve提取数据与添加泛型，失败通过reject捕捉错误。

/**



 * 请求函数



 * @param  UniApp.RequestOptions



 * @returns Promise



 *  1. 返回 Promise 对象，用于处理返回值类型



 *  2. 获取数据成功



 *    2.1 提取核心数据 res.data



 *    2.2 添加类型，支持泛型



 *  3. 获取数据失败



 *    3.1 401错误  -> 清理用户信息，跳转到登录页



 *    3.2 其他错误 -> 根据后端错误信息轻提示



 *    3.3 网络错误 -> 提示用户换网络



 */



type Data<T> = {



  code: string



  msg: string



  result: T



}



// 2.2 添加类型，支持泛型



export const http = <T>(options: UniApp.RequestOptions) => {



  // 1. 返回 Promise 对象



  return new Promise<Data<T>>((resolve, reject) => {



    uni.request({



      ...options,



      // 响应成功



      success(res) {



        // 状态码 2xx，参考 axios 的设计



        if (res.statusCode >= 200 && res.statusCode < 300) {



          // 2.1 提取核心数据 res.data



          resolve(res.data as Data<T>)



        } else if (res.statusCode === 401) {



          // 401错误  -> 清理用户信息，跳转到登录页



          const memberStore = useMemberStore()



          memberStore.clearProfile()



          uni.navigateTo({ url: '/pages/login/login' })



          reject(res)



        } else {



          // 其他错误 -> 根据后端错误信息轻提示



          uni.showToast({



            icon: 'none',



            title: (res.data as Data<T>).msg || '请求错误',



          })



          reject(res)



        }



      },



      // 响应失败



      fail(err) {



        uni.showToast({



          icon: 'none',



          title: '网络错误，换个网络试试',



        })



        reject(err)



      },



    })



  })



}

八 . 其他配置

1. vue3自动按需导入：

在使用vue3的方法如‘ref’等需要手动进行导入很麻烦，这里使用到插件unplugin-auto-import可以实现自动按需导入，官网：unplugin-auto-import - npm

安装：

npm i unplugin-auto-import -save

vue.config.js文件中添加配置：

//vite.config.ts



 



import { defineConfig } from 'vite'



import uni from '@dcloudio/vite-plugin-uni'



import AutoImport from 'unplugin-auto-import/vite'



 



// https://vitejs.dev/config/



export default defineConfig({



  build: {



    sourcemap: process.env.NODE_ENV === 'development',



  },



  plugins: [



    uni(),



    AutoImport({ // 使用



      imports: ['vue'],



      dts: 'src/auto-import.d.ts',



      // 如有用到eslint记得加上写段，没有用到可以忽略



      eslintrc: {



        enabled: true,



      },



    })



  ],



})

.eslintrc.js文件配置（用到eslint才配置）：

//.eslintrc.js



  extends: [



    'plugin:vue/vue3-essential',



    'eslint:recommended',



    '@vue/eslint-config-typescript',



    '@vue/eslint-config-prettier',



    'plugin:prettier/recommended', // 添加 prettier 插件,



  ],

配置完成后重新启动一下项目就可以啦！

---

欢迎各位大佬讨论、提供建议补充…