Vue3+Vite+UniApp+UnoCSS 跨平台开发模板：开箱即用，极速开发

前言

随着跨平台开发的需求日益增长，如何快速搭建一套高效、可维护的 UniApp 开发环境成为前端开发者的刚需。本文将分享一套基于 Vite + Vue3 + UniApp + UnoCSS 的跨平台开发模板，集成了自动导入、组件自动注册、Pinia 状态管理、Sass 预处理器等实用特性，支持 H5、微信小程序、支付宝小程序等多端开发，开箱即用，大幅提升开发效率。

🎯 模板特性

• 🚀极速构建：基于 Vite 构建，冷启动和热更新速度远超传统 webpack，开发体验拉满；
• 📱全端兼容：支持 UniApp 全平台（H5、微信 / 支付宝 / 抖音 / 百度 / QQ 小程序、App 等）；
• 💚Vue3 生态：全面拥抱 Vue3 Composition API，语法简洁，逻辑复用更高效；
• 🎨原子化 CSS：集成 UnoCSS，告别冗余样式，用原子类快速构建 UI；
• 📦状态管理：内置 Pinia，轻量高效，替代 Vuex 的新一代状态管理方案；
• 🔧自动导入：Vue API、Pinia 自动导入，无需手动 import，减少冗余代码；
• 🧩组件自动注册：组件目录约定式注册，无需手动全局注册；
• 💅样式增强：支持 Sass 预处理器，满足复杂样式编写需求；
• 🎨代码规范：集成 Prettier，保证代码格式统一。

📦 快速上手

环境要求

• Node.js >= 16
• 包管理工具：pnpm（推荐）/npm/yarn

安装与开发

1. 克隆模板（或直接下载）

# 克隆仓库（如果是自建仓库） git clone https://github.com/xxx/vue3-uni-unocss.git cd vue3-uni-unocss

2. 安装依赖

pnpm install # 或 npm install / yarn install

3. 启动开发环境

• H5 开发：

pnpm dev:h5

• 微信小程序开发：

pnpm dev:mp-weixin

• 支付宝小程序开发：

pnpm dev:mp-alipay

• 其他平台（抖音 / 百度 / QQ 小程序等）：

# 抖音小程序 pnpm dev:mp-toutiao # 百度小程序 pnpm dev:mp-baidu # QQ小程序 pnpm dev:mp-qq

4. 构建生产包

# H5构建 pnpm build:h5 # 微信小程序构建 pnpm build:mp-weixin # 其他平台同理，替换对应指令 pnpm build:mp-alipay

🛠 核心配置解析

1. Vite 配置（vite.config.js）

核心配置集成了 UnoCSS、自动导入、组件自动注册、UniApp 插件等，关键代码如下：

import { defineConfig } from 'vite' import { fileURLToPath, URL } from 'node:url' import uni from '@dcloudio/vite-plugin-uni' import AutoImport from 'unplugin-auto-import/vite' import Components from 'unplugin-vue-components/vite' export default defineConfig(async () => { const { default: UnoCSS } = await import('unocss/vite') return { plugins: [ UnoCSS(), // 集成UnoCSS // 自动导入Vue、Pinia API AutoImport({ imports: ['vue', 'pinia'] }), // 自动注册components目录下的组件 Components({ dirs: ['src/components'] }), uni() // UniApp核心插件 ], // 路径别名：@指向src目录 resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } }, // Sass预处理器配置 css: { preprocessorOptions: { scss: { api: 'modern-compiler', silenceDeprecations: ['legacy-js-api'] } } } } })

2. UnoCSS 配置（unocss.config.js）

针对 UniApp / 小程序适配的 UnoCSS 配置，支持属性化模式和类名转换：

import presetWeapp from 'unocss-preset-weapp' import { extractorAttributify, transformerClass } from 'unocss-preset-weapp/transformer' const { presetWeappAttributify, transformerAttributify } = extractorAttributify() export default { presets: [presetWeapp(), presetWeappAttributify()], // 小程序预设 + 属性化预设 transformers: [transformerAttributify(), transformerClass()] // 转换属性化/类名适配小程序 }

🚀 核心功能使用示例

1. UnoCSS 原子化样式使用

无需编写传统 CSS，直接通过原子类快速构建 UI：

<template> <view class="p-4 bg-red-500 text-white rounded-lg flex items-center justify-center"> 这是一个原子化样式卡片 </view> </template>

常用原子类分类：

• 布局：flex、grid、items-center、justify-center；
• 间距：p-4（内边距）、m-2（外边距）、mx-5（水平外边距）；
• 颜色：bg-red-500（背景色）、text-blue（文字色）；
• 文字：text-2xl（字号）、font-bold（加粗）、text-center（居中）；
• 圆角：rounded、rounded-full（圆形）。

2. 自动导入特性

Vue3 的 Composition API（ref、reactive、computed 等）、Pinia 无需手动 import，直接使用：

<script setup> // 无需 import { ref } from 'vue' const count = ref(0) // 无需 import { defineStore } from 'pinia' const useUserStore = defineStore('user', { state: () => ({ name: 'Vue3' }) }) const userStore = useUserStore() </script>

3. 组件自动注册

将组件放在src/components/目录下，直接在页面中使用，无需注册：

<!-- src/components/MyButton.vue --> <template> <button class="px-4 py-2 bg-blue-500 text-white rounded">自定义按钮</button> </template> <!-- 页面中直接使用 --> <template> <MyButton /> </template>

4. 路径别名使用

@指向src目录，简化路径导入：

// 导入页面组件 import Home from '@/pages/home/index.vue' // 导入工具函数 import { formatTime } from '@/utils/date.js'

📁 项目结构

plaintext

vue3-uni-unocss/ ├── src/ │ ├── pages/ # 页面目录（对应pages.json路由） │ ├── components/ # 组件目录（自动注册） │ ├── static/ # 静态资源（图片、字体等） │ ├── utils/ # 工具函数目录（可选） │ ├── App.vue # 应用根组件 │ ├── main.js # 入口文件 │ ├── pages.json # UniApp路由配置 │ └── manifest.json # 应用配置（多端适配） ├── vite.config.js # Vite核心配置 ├── unocss.config.js # UnoCSS配置 ├── package.json # 依赖与脚本配置 ├── .prettierrc # Prettier格式化配置 └── index.html # H5入口文件

🎨 开发规范与最佳实践

1. 新增页面

1. 在src/pages/下创建页面目录（如home/index.vue）；
2. 在src/pages.json中配置路由：

json

{ "pages": [ { "path": "pages/home/index", "style": { "navigationBarTitleText": "首页" } } ] }

2. 状态管理

使用 Pinia 管理全局状态，示例：

javascript

运行

// src/store/user.js export const useUserStore = defineStore('user', { state: () => ({ token: '', userInfo: null }), actions: { setToken(token) { this.token = token }, setUserInfo(info) { this.userInfo = info } } })

3. 多端适配

利用 UniApp 的条件编译语法，适配不同平台：

vue

<template> <!-- H5端显示 --> <!-- #ifdef H5 --> <view class="h5-only">H5专属内容</view> <!-- #endif --> <!-- 微信小程序端显示 --> <!-- #ifdef MP-WEIXIN --> <view class="wx-only">微信小程序专属内容</view> <!-- #endif --> </template>

📌 常见问题解决

1. UnoCSS 样式在小程序不生效：检查unocss.config.js是否配置了小程序预设和转换器，确保transformerClass和transformerAttributify已启用；
2. 自动导入失效：确认unplugin-auto-import版本与 Vite 兼容，且imports配置包含需要自动导入的模块；
3. Sass 编译报错：确保安装了sass依赖（pnpm add sass -D），且 Vite 的 scss 配置使用modern-compilerAPI；
4. 路径别名报错：检查vite.config.js中@别名是否正确指向src目录，且文件导入时路径书写正确。

总结

这套 Vue3+UniApp+UnoCSS 模板整合了当下前端开发的主流技术栈，解决了 UniApp 开发中样式管理、代码冗余、多端适配等痛点，开箱即用的特性让开发者可以快速聚焦业务开发，而非环境配置。无论是个人项目还是团队协作，这套模板都能大幅提升开发效率和代码可维护性。

如果觉得这套模板有帮助，欢迎点赞收藏，也可以根据自己的业务需求扩展更多特性（如请求封装、权限管理、国际化等）。

附：完整依赖清单

核心依赖版本（package.json）：

• Vue：^3.5.33
• UniApp：3.0.0+
• Vite：5.2.8
• UnoCSS：0.62.3
• UnoCSS Preset Weapp：^66.0.2
• Pinia：^2.1.7
• unplugin-auto-import：0.18.6
• unplugin-vue-components：0.27.4
• Sass：^1.99.0