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

目录

一.  创建 uni-app 项目

二. 编译和运行 uni-app 项目

三. TS 类型校验

四. JSON 注释问题

五. 安装uview-plus 

 六. 配置pinia持久化

七. 封装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 项目

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 插件,
  ],

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

---

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