uni-app+vue3+ts项目搭建完整流程

摘要

项目代码同步更新至码云 uni-vue3-ts-template利用 uni-app 开发，有两种方法：这里我们使用第2种方法，这两种方法官方都有详细介绍 点击查看官方文档

项目代码同步更新至码云 uni-vue3-ts-template

开发前准备

利用 uni-app 开发，有两种方法：

1. 通过 HBuilderX 创建（需安装 HBuilderX 编辑器）
2. 通过命令行创建（需安装 NodeJS 环境），推荐使用 vscode 编辑器

这里我们使用第2种方法，这两种方法官方都有详细介绍 点击查看官方文档

vscode 安装插件

1. 安装 Vue3 插件，点击查看官方文档

• 安装 Vue Language Features (Volar) ：Vue3 语法提示插件
• 安装 TypeScript Vue Plugin (Volar) ：Vue3+TS 插件
• 工作区禁用 Vue2 的 Vetur 插件(Vue3 插件和 Vue2 冲突)
• 工作区禁用 @builtin typescript 插件（禁用后开启 Vue3 的 TS 托管模式）

2. 安装 uni-app 开发插件

• uni-create-view ：快速创建 uni-app 页面
• uni-helper（插件套装，安装一个后会有多个插件） ：代码提示
• uniapp小程序扩展 ：鼠标悬停查文档

uni-create-view 插件使用

uni-create-view 安装后，需要修改配置，进入 文件 -> 首选项 -> 设置，按以下选项修改即可

uni-create-view 使用方法：
在 src/pages 下右键，选择 新建uni-app页面，弹出输入框，输入 文件夹名称 页面名称，然后回车

生成如下目录文件

并且在 src/pages.json 目录下，已将新界面配置进去

vscode 项目配置

项目生成后，在项目的根目录进行
新建 .vscode 文件夹，并创建 settings.json 文件：

{   // 在保存时格式化文件   "editor.formatOnSave": true,   // 文件格式化配置   "[vue]": {     "editor.defaultFormatter": "esbenp.prettier-vscode"   },   "[json]": {     "editor.defaultFormatter": "esbenp.prettier-vscode"   },   // 配置语言的文件关联   "files.associations": {     "pages.json": "jsonc", // pages.json 可以写注释     "manifest.json": "jsonc" // manifest.json 可以写注释   } } 

同样，在 .vscode 文件夹内，创建 vue3 模板文件，命名为 vue3-uniapp.code-snippets：

{   "vue3+uniapp快速生成模板": {     "scope": "vue",     "prefix": "Vue3",     "body": [       "<script setup lang="ts">",       "$2",       "</script>n",       "<template>",       "t<view class="">test</view>",       "</template>n",       "<style lang="scss"></style>",       "$2"     ],     "description": "vue3+uniapp快速生成模板"   } } 

然后，在空白vue文件中，输入vue3，选择此模板，即可快速生成代码

项目初始化

项目创建

拉取 uni-app 官方项目基础架构代码 https://uniapp.dcloud.net.cn/quickstart-cli.html

npx degit dcloudio/uni-preset-vue#vite-ts uni-vue3-ts-shop  cd uni-vue3-ts-shop 

或者直接直接克隆国内 gitee 地址，然后修改项目名称，并进入项目根目标

git clone -b vite-ts https://gitee.com/dcloud/uni-preset-vue.git 

安装ts扩展

主要是为了增加 uni-app 、微信小程序、nodejs 对ts的支持

npm i -D @uni-helper/uni-app-types miniprogram-api-typings @types/node 

修改 tsconfig.json

{   "compilerOptions": {     "ignoreDeprecations": "5.0",     "allowJs": true,     },     "types": ["@dcloudio/types", "miniprogram-api-typings", "@uni-helper/uni-app-types"]   },   "vueCompilerOptions": {     // experimentalRuntimeMode 已废弃，现调整为 nativeTags，请升级 Volar 插件至最新版本     "nativeTags": ["block", "component", "template", "slot"]   } } 

配置环境变量

点我查看官方文档

新增env文件

根目录下新建 .env 文件

VITE_HTTP = https://mock.mengxuegu.com/mock/6598258423a3c638568501db/uniapp_template 

使用

获取环境变量

process.env.NODE_ENV          // 应用运行的模式，比如vite.config.ts里 import.meta.env.VITE_HTTP     // src下的vue文件或其他ts文件里 

开启 sourcemap

点我查看官方文档
修改 vite.config.ts 文件：

export default defineConfig({   build: {     // 开发阶段启用源码映射：https://uniapp.dcloud.net.cn/tutorial/migration-to-vue3.html#需主动开启-sourcemap     sourcemap: process.env.NODE_ENV === 'development',   },   plugins: [uni()], }) 

统一代码规范

安装 prettier

npm i -D prettier 

根目录下新建 .prettierrc.json

{   "singleQuote": true,   "semi": false,   "printWidth": 120,   "trailingComma": "all",   "endOfLine": "auto" } 

安装 eslint

npm i -D eslint eslint-plugin-vue @rushstack/eslint-patch @vue/eslint-config-typescript  @vue/eslint-config-prettier 

根目录下新建 .eslintrc.js

/* eslint-env node */ require('@rushstack/eslint-patch/modern-module-resolution')  module.exports = {   root: true,   extends: [     'plugin:vue/vue3-essential',     'eslint:recommended',     '@vue/eslint-config-typescript',     '@vue/eslint-config-prettier',   ],   // 小程序全局变量   globals: {     uni: true,     wx: true,     WechatMiniprogram: true,     getCurrentPages: true,     getApp: true,     UniApp: true,     UniHelper: true,     App: true,     Page: true,     Component: true,     AnyObject: true,   },   parserOptions: {     ecmaVersion: 'latest',   },   rules: {     'prettier/prettier': [       'warn',       {         singleQuote: true,         semi: false,         printWidth: 120,         trailingComma: 'all',         endOfLine: 'auto',       },     ],     'vue/multi-word-component-names': ['off'],     'vue/no-setup-props-destructure': ['off'],     'vue/no-deprecated-html-element-is': ['off'],     '@typescript-eslint/no-unused-vars': ['off'],   }, } 

package.json 中新增命令 lint

{   "scripts": {     "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"   } } 

然后运行 npm run lint，将项目内的文件格式化为 eslint 规定的格式（这个命令可随时运行，以便有新页面/插件加入时，解决代码风格的问题）

规范git提交

非必需，适合多人开发

安装 husky

安装并初始化 husky

npx husky-init 

如果是首次安装，会有以下提示，输入 y 回车即可

Need to install the following packages: husky-init@8.0.0 Ok to proceed? (y) 

安装完成后，会多出 .husky 文件夹和 pre-commit 文件

安装 lint-staged

npm i -D lint-staged 

安装完成后配置 package.json

{   "script": {     // ... 省略 ...     "lint-staged": "lint-staged"   },   "lint-staged": {     "*.{vue,ts,js}": ["eslint --fix"]   } } 

修改 pre-commit 文件

- npm test + npm run lint-staged 

提交规范

至此，已完成 husky + lint-staged 的配置。之后，每次提交代码，在提交信息前都要加入以下提交类型之一，譬如：feat: 首页新增轮播图

提交字段	说明
feat:	增加新功能
fix:	修复问题/BUG
style:	代码风格相关无影响运行结果的
perf:	优化/性能提升
refactor:	重构
revert:	撤销修改
test:	测试相关
docs:	文档/注释
chore:	依赖更新/脚手架配置修改等
workflow:	工作流改进
ci:	持续集成
types:	类型定义文件更改
wip:	开发中

安装 uni-ui 组件库

非必需，也可使用其他组件库

uni-ui 是DCloud提供的一个跨端ui库，它是基于vue组件的、flex布局的、无dom的跨全端ui框架。查看官方文档

安装 uni-ui 及相关插件

sass sass-loader 是 uni-ui 的依赖库，@uni-helper/uni-ui-types 是类型声明文件

npm i  -D sass sass-loader npm i @dcloudio/uni-ui npm i -D @uni-helper/uni-ui-types 

修改配置

修改 tsconfig.json，配置类型声明文件

{   "compilerOptions": {     "types": ["@dcloudio/types", "miniprogram-api-typings", "@uni-helper/uni-app-types", "@uni-helper/uni-ui-types"]   } } 

修改 src/pages.json，配置自动导入组件

{   "easycom": {     "autoscan": true,     "custom": {       // uni-ui 规则如下配置         "^uni-(.*)": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue"      }   },   "pages": [     // ……   ] } 

安装配置 pina

安装

pinia-plugin-persistedstate 是持久化 pina 插件

npm i pinia pinia-plugin-persistedstate 

使用

在 src 下新增以下目录和文件

src ├─stores │  ├─modules │  │ └─user.ts |  └─index.ts 

user.ts

import { defineStore } from 'pinia' import { ref } from 'vue'  // 定义 Store export const useMemberStore = defineStore(   'user',   () => {     // 用户信息     const userInfo = ref<any>()      // 保存用户信息，登录时使用     const setUserInfo = (val: any) => {       userInfo.value = val     }      // 清理用户信息，退出时使用     const clearUserInfo = () => {       userInfo.value = undefined     }      return {       userInfo,       setUserInfo,       clearUserInfo,     }   },   // TODO: 持久化   {     persist: true,   }, ) 

index.ts

import { createPinia } from 'pinia' import persist from 'pinia-plugin-persistedstate'  // 创建 pinia 实例 const pinia = createPinia() // 使用持久化存储插件 pinia.use(persist)  // 默认导出，给 main.ts 使用 export default pinia  // 模块统一导出 export * from './modules/user' 

main.ts

import { createSSRApp } from 'vue' import pinia from './stores'  import App from './App.vue' export function createApp() {   const app = createSSRApp(App)    app.use(pinia)   return {     app,   } }  

持久化

插件默认使用 localStorage 实现持久化，小程序端不兼容，需要替换持久化 API。
修改 stores/modules/user.ts

export const useUserStore = defineStore(   'member',   () => {     //…省略   },   {     // 配置持久化     persist: {       // 调整为兼容多端的API       storage: {         setItem(key, value) {           uni.setStorageSync(key, value)          },         getItem(key) {           return uni.getStorageSync(key)          },       },     },   }, ) 

封装请求

uniapp 拦截器

uni.addInterceptor 的使用参考 官方文档

src 目录下新建 utils 文件夹，并新建 http.ts 文件

import { useUserStore } from '@/stores'  const baseURL = import.meta.env.VITE_HTTP  // 拦截器配置 const httpInterceptor = {   // 拦截前触发   invoke(options: UniApp.RequestOptions) {     // 非 http 开头需拼接地址     if (!options.url.startsWith('http')) {       options.url = baseURL + options.url     }     options.timeout = 10000     // 添加请求头标识     options.header = {       'request-client': 'wechart-app',       ...options.header,     }     // 添加 token 请求头标识     const memberStore = useUserStore()     const token = memberStore.userInfo?.token     if (token) {       options.header.Authorization = token     }   }, }  // 拦截 request 请求 uni.addInterceptor('request', httpInterceptor) // 拦截 uploadFile 文件上传 uni.addInterceptor('uploadFile', httpInterceptor) 

由于 uni-app 的响应拦截器对类型支持并不友好，所以我们自行封装响应拦截器，同一个文件，继续

/**  * 请求函数  * @param  UniApp.RequestOptions  * @returns Promise  */ // Data类型根据后台返回数据去定义 type Data<T> = {   code: string   msg: string   result: T } export const http = <T>(options: UniApp.RequestOptions) => {   return new Promise<Data<T>>((resolve, reject) => {     uni.request({       ...options,       // 响应成功       success(res) {         if (res.statusCode >= 200 && res.statusCode < 300) {           resolve(res.data as Data<T>)         } else if (res.statusCode === 401) {           // 401错误  -> 清理用户信息，跳转到登录页           const userStore = useUserStore()           userStore.clearUserInfo()           uni.navigateTo({ url: '/pages/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)       },     })   }) } 

使用

为了统一API文件，我们在 src 目录下新建 api 文件夹，并新建 user.ts

import { http } from '@/utils/http'  export const getUserInfoAPI = (data: any) => {   return http({     url: '/user/info',     method: 'POST',     data,   }) } 

然后在需要的地方调用，比如在 page/my/index.vue 里调用：

<script setup lang="ts"> import { useUserStore } from '@/stores' import { getUserInfoAPI } from '@/api/user'  const userStore = useUserStore()  const getUserInfo = async () => {   const res = await getUserInfoAPI({ id: 'weizwz' })   console.log(res)   const { result } = res   userStore.setUserInfo(result) } </script>  <template>   <view class="">     <view>用户信息： {{ userStore.userInfo }}</view>     <button       @tap="         userStore.setUserInfo({           userName: 'weizwz',         })       "       size="mini"       plain       type="primary"     >       保存用户信息     </button>     <button @tap="userStore.clearUserInfo()" size="mini" plain type="primary">清理用户信息</button>     <button @tap="getUserInfo()" size="mini" plain type="primary">发送请求</button>   </view> </template>  <style lang="scss"></style> 

效果如下，可以看到已经调用成功：

如果调用被拦截的话，请检查微信小程序里的项目设置，然后选中 不检验合法域名、web-view(业务域名)、TLS版本以及HTTPS证书 选项

注意事项

开发区别

uni-app 项目每个页面是一个 .vue 文件，数据绑定及事件处理同 Vue.js 规范：

1. vue文件中的 div 标签需替换为 view 标签
2. 属性绑定 src="{ { url }}" 升级成 :src="url"
3. 事件绑定 bindtap="eventName" 升级成 @tap="eventName"，支持（）传参
4. 支持 Vue 常用指令 v-for、v-if、v-show、v-model 等

其他补充

1. 调用接口能力，建议前缀 wx 替换为 uni ，养成好习惯，支持多端开发。
2. <style> 页面样式不需要写 scoped，小程序是多页面应用，页面样式自动隔离。
3. 生命周期分三部分：应用生命周期(小程序)，页面生命周期(小程序)，组件生命周期(Vue)
4. 其他参考 uniapp-vue语法 官方文档

文章部分内容来自 小兔鲜儿项目 ，本文主要是在此基础上补全了完整创建此项目的流程和所需的依赖