推荐阅读：
🔥 uView Pro 正式开源！70+ Vue3 组件重构完成，uni-app 组件库新晋之星
本文面向希望快速搭建 uni-app 项目的开发者与团队，介绍如何使用 create-uni 脚手架一键创建项目，如何在项目中引入并配置 uView Pro 组件库，以及如何利用 uni-helper 系列插件（vite-plugin、unocss 等）提高开发效率。
一、为什么选择 create-uni + uView Pro？
在 uniapp 构建的多端工程中，速度与一致性至关重要。
create-uni 提供一键生成、模板丰富的项目引导能力，而 uView Pro 则是基于 Vue3 + TypeScript 全面重构的高质量 uni-app 组件库。两者结合，能带来：
- 快速上手：一行命令生成标准化项目结构；
- 现代开发体验：Vite + Vue3 + TS，热更新快、类型友好；
- 丰富组件：70+ 高质量组件覆盖主流业务场景；
- 高度可扩展：uni-helper 插件体系支持文件路由、按需组件、布局系统等；
- 企业友好：模板、样式、规范一致，便于团队协作与维护。
二、准备工作（环境与工具）
在开始之前，建议准备以下环境：
- Node.js（建议 LTS 版本，如 18.x 或 20.x）
- pnpm / npm / yarn（推荐 pnpm，速度更快且适合 monorepo）
- VS Code + Volar（强烈推荐，Vue3 + TypeScript 最佳搭配，禁用 Vetur）
- HBuilderX（如果需要使用 HBuilderX 工具链或插件市场，非必要不使用）
确保全局工具可用：
# 建议使用 pnpm
npm install -g pnpm
# 若需要全局安装脚手架（可选）
npm install -g @dcloudio/uni-app
三、使用 create-uni 快速创建项目（一步到位）
create-uni 是一套现代化脚手架，支持选择模板、快速集成 uView Pro 组件库等，下面给出用 pnpm create 的推荐流程：
# 使用 create-uni（交互式选择项目模板）
pnpm create uni@latest
cd my-uni-project
pnpm install
# 启动开发（以 H5 为例）
pnpm run dev:h5
在交互式选择时，选择需要的插件和库、选择需要的组件库 uView Pro ，可以让项目开箱即用：根据您的选择可以帮助您自动集成 uView Pro、UnoCSS、uni-helper 等插件，省去大量配置时间。
示例：
-
选择需要的 vite 插件时勾选必要的插件：
- vite-plugin-uni-pages（提供基于文件系统的路由）
- vite-plugin-uni-components（按需自动引入组件）
- vite-plugin-uni-layouts（提供类 nuxt 的 layouts 系统）
- vite-plugin-uni-manifest（自动生成 manifest.json 文件）
-
选择需要的库时勾选必要的库：
-
选择 UI 组件库时勾选 uView Pro
通过以上选择完成后，脚手架会自动创建包含以下内容的项目：
- Vite + uni-app 项目骨架
-
uview-pro 依赖与全局样式引入（index.scss / theme.scss）
- 推荐的
tsconfig.json 与 vite.config.ts 配置
- UnoCSS 与 uni-helper 插件预配置
四、手动在已存在项目中安装 uView Pro（npm 或 uni_modules）
如果你已用其它方式创建项目，并不是使用 create-uni，下面是两种常见安装方式，分别适用于 CLI 项目（npm）与 HBuilderX 项目（uni_modules）。
1. CLI（npm / pnpm）方式（推荐团队/CLI 项目）
pnpm add uview-pro
# 或者 npm install uview-pro --save
在 Vue3 项目中，全局引入并注册：
// main.ts
import { createSSRApp } from "vue";
import uViewPro from "uview-pro";
export function createApp() {
const app = createSSRApp(App);
app.use(uViewPro);
return {
app,
};
}
在 uni.scss 中引入主题：
@import "uview-pro/theme.scss";
在 App.vue 首行引入基础样式：
<style lang="scss">
@import "uview-pro/index.scss";
</style>
在 pages.json / vite 的 easycom 配置中添加：
"easycom": {
"autoscan": true,
"custom": {
"^u-(.*)": "uview-pro/components/u-$1/u-$1.vue"
}
}
也可以使用@uni-helper/vite-plugin-uni-components（基于文件的按需组件引入）插件来替换 easycom 的方式，详细使用方式见下述介绍。
注：CLI npm 方式更易管理版本、配合 TypeScript 与 Volar 获得更好类型提示体验。
2. HBuilderX（uni_modules）方式（推荐 HBuilderX 项目）
将 uview-pro 目录放入项目 uni_modules 下（或通过插件市场安装）；
DCloud 插件市场：ext.dcloud.net.cn/plugin?id=2…
在main.ts全局引入并注册
// main.ts
import { createSSRApp } from 'vue'
import uViewPro from "@/uni_modules/uview-pro";
export function createApp() {
const app = createSSRApp(App)
app.use(uViewPro)
return {
app
}
}
在 pages.json 中配置 easycom：
"easycom": {
"autoscan": true,
"custom": {
"^u-(.*)": "@/uni_modules/uview-pro/components/u-$1/u-$1.vue"
}
}
在 uni.scss 中引入主题：
@import "@/uni_modules/uview-pro/theme.scss";
在 App.vue 首行引入基础样式：
<style lang="scss">
@import "@/uni_modules/uview-pro/index.scss";
</style>
HBuilderX 下，uni_modules 更符合编辑器和打包器的约定，部分原生插件或小程序构建会更兼容。
因此：建议 CLI 项目使用 npm/pnpm 方式，HBuilderX 项目使用 uni_modules 方式
五、结合 uni-helper 插件提升开发效率
uni-helper 系列插件在 vite + uni-app 生态下提供了大量现代化的便利能力。下面按插件逐一介绍它们的作用、安装、配置示例、与 uView Pro 的配合要点以及常见注意事项。
更多用法及插件请访问 uni-helper 官网文档：uni-helper.js.org/
1. @uni-helper/vite-plugin-uni-pages（文件系统路由）
作用：
- 自动扫描
src/pages 或 pages 目录，基于文件系统生成路由配置，替代手动维护 pages.json 的繁琐流程；
- 支持页面元数据、分组、全局样式定义和路由扩展；
- 提供
virtual:uni-pages 等虚拟模块用于在代码中读取页面信息，便于构建菜单、统计或自动化文档。
安装：
pnpm add -D @uni-helper/vite-plugin-uni-pages
基本配置（vite.config.ts）：
import { defineConfig } from "vite";
import Uni from "@uni-helper/plugin-uni";
import UniPages from "@uni-helper/vite-plugin-uni-pages";
export default defineConfig({
plugins: [UniPages(), Uni()],
});
pages 配置示例（pages.config.ts）：
import { defineUniPages } from "@uni-helper/vite-plugin-uni-pages";
export default defineUniPages({
pages: [],
globalStyle: {
navigationBarTextStyle: "black",
navigationBarTitleText: "MyApp",
},
subPackages: [],
});
在代码中获取页面元数据：
/// <reference types="@uni-helper/vite-plugin-uni-pages/client" />
import { pages } from "virtual:uni-pages";
console.log(pages);
与 uView Pro 的配合要点：
- 结合
uView Pro Starter，路由自动化能让示例页面、文档 demo 与项目页面保持一致；
- 当需要在页面自动注入组件演示或 demo 链接时，
pages 元数据非常方便。
注意事项：
- 如果同时存在手动维护的
pages.json，请确认插件优先级与覆盖规则；
- 某些小程序平台对动态生成的路由有特殊限制，发布前务必在目标平台做真机测试。
2. @uni-helper/vite-plugin-uni-components（基于文件的按需组件引入）
作用：
- 基于文件系统实现组件按需自动引入，类似于 Vue 的
unplugin-vue-components，但针对 uni-app 场景优化；
- 可以替代
easycom 的全局扫描，减少启动扫描成本并提升按需加载精度；
- 支持自定义规则、扩展第三方组件库的映射。
安装：
pnpm add -D @uni-helper/vite-plugin-uni-components
配置示例，已经支持 uView Pro Resolver：
import { defineConfig } from "vite";
import Uni from "@uni-helper/plugin-uni";
import UniComponents from "@uni-helper/vite-plugin-uni-components";
import { uViewProResolver } from "@uni-helper/vite-plugin-uni-components/resolvers";
export default defineConfig({
plugins: [
UniComponents({
dts: true,
resolvers: [uViewProResolver()],
}),
Uni(),
],
});
与 uView Pro 的配合要点：
- 使用此插件可避免在
pages.json 中重复写 easycom 规则；
- 当配合
uview-pro 时，需要引入 uViewProResolver 使用；
- 有助于实现按需打包，减小 H5 与小程序包体积。
注意事项：
- 部分平台（例如 HBuilderX 的旧版本）可能仍需要
pages.json 的支持，务必在迁移前做兼容性验证；
- 对于同名组件（不同来源）要明确命名或使用手动 import 以避免歧义。
3. @uni-helper/vite-plugin-uni-layouts（布局系统）
作用：
- 在 uni-app 中实现类似 Nuxt 的布局机制（layouts），支持多个 layout 组件、slot、以及按页面应用布局；
- 自动扫描
src/layouts 并将页面包裹在指定布局下，简化头部/尾部/侧边栏等公共区域维护。
安装：
pnpm add -D @uni-helper/vite-plugin-uni-layouts
配置示例：
import { defineConfig } from "vite";
import Uni from "@uni-helper/plugin-uni";
import UniLayouts from "@uni-helper/vite-plugin-uni-layouts";
export default defineConfig({
plugins: [UniLayouts(), Uni()],
});
使用示例：
- 在
src/layouts/default.vue 中定义布局：
<template>
<div class="layout">
<slot name="header">默认头部</slot>
<slot>主内容</slot>
<slot name="footer">默认底部</slot>
</div>
</template>
<script setup>
definePage({ layout: "default" });
</script>
与 uView Pro 的配合要点：
- 布局中可直接使用
uView Pro 的导航栏、Tabbar、Footer 等组件，保证风格统一；
- 结合
uView Pro Starter，布局示例通常已经内置，直接复用即可。
注意事项：
- 在微信小程序中如果页面使用
web-view，布局插件的包裹机制可能不生效；
- 动态切换布局时注意保持页面状态。
4. @uni-helper/vite-plugin-uni-manifest（用 TypeScript 管理 manifest）
作用：
- 允许使用 TypeScript 编写
manifest.json（如 manifest.config.ts），享受类型提示与可组合的配置方式；
- 在构建时自动生成标准
manifest.json，并支持按平台差异化配置。
安装：
pnpm add -D @uni-helper/vite-plugin-uni-manifest
配置示例：
import Uni from "@uni-helper/plugin-uni";
import UniManifest from "@uni-helper/vite-plugin-uni-manifest";
export default defineConfig({
plugins: [UniManifest(), Uni()],
});
示例 manifest.config.ts：
import { defineManifestConfig } from "@uni-helper/vite-plugin-uni-manifest";
export default defineManifestConfig({
appid: "your-appid",
name: "MyApp",
versionName: "1.0.0",
h5: {
devServer: {
port: 8080,
},
},
});
与 uView Pro 的配合要点：
- 将 theme 或构建相关的配置以类型化方式管理，便于在不同环境（dev/staging/prod）间切换；
- 在企业项目中能更方便地实现 CI 自动化生成不同渠道包的 manifest 配置。
注意事项：
- 生成的 manifest.json 应在真机或云打包平台上验证，避免配置项平台不兼容。
5. @uni-helper/vite-plugin-uni-platform（按平台文件替换）
作用：
- 支持基于文件名的按平台编译，例如
index.h5.vue、index.mp-weixin.vue、index.app.vue 等，构建时自动替换为对应平台文件；
- 便于按平台做差异化实现，同时保持统一的项目结构与代码管理。
安装：
pnpm add -D @uni-helper/vite-plugin-uni-platform
配置示例：
import Uni from "@uni-helper/plugin-uni";
import UniPlatform from "@uni-helper/vite-plugin-uni-platform";
export default defineConfig({
plugins: [UniPlatform(), Uni()],
});
使用说明：
- 在项目中创建文件如
pages/index.h5.vue 针对 H5 的实现，pages/index.mp-weixin.vue 针对微信小程序的实现；
- 在编译目标为 H5 时，会优先使用
index.h5.vue，否则退回 index.vue。
与 uView Pro 的配合要点：
- 当使用 uView Pro 的某些平台相关适配（例如原生 SDK 或特定 API）时，可以在平台特定文件中做针对性封装；
- 结合
uni-pages，能更方便地管理平台差异化页面列表。
注意事项：
- 使用大量平台特异化文件会增加维护成本，建议仅在必要场景使用。
6. @uni-helper/unocss-preset-uni（UnoCSS 预设）
作用：
- 为 uni-app 定制的 UnoCSS 预设，开箱即用的原子类工具集，支持属性化写法与按平台样式差异；
- 极大减少重复样式、提高开发速度，同时配合 Uno 的即时编译，开发体验流畅。
安装：
pnpm add -D @uni-helper/unocss-preset-uni unocss unocss-applet
vite 配置示例：
import { defineConfig } from "vite";
import Uni from "@uni-helper/plugin-uni";
import UnoCSS from "unocss/vite";
export default defineConfig({
plugins: [Uni(), UnoCSS()],
});
uno.config.ts 配置
import { presetUni } from "@uni-helper/unocss-preset-uni";
import {
defineConfig,
presetIcons,
transformerDirectives,
transformerVariantGroup,
} from "unocss";
export default defineConfig({
presets: [
presetUni({
attributify: {
// UnoCSS的解析规则可与uView Pro组件库内置样式冲突
ignoreAttributes: ["size"],
},
}),
],
transformers: [transformerDirectives(), transformerVariantGroup()],
});
与 uView Pro 的配合要点：
- UnoCSS 非侵入式，可与 uView Pro 的 SCSS 主题变量共存；
- 在快速原型或设计系统中，Uno 的原子类能极大提升迭代速度；
- 推荐将设计变量（颜色、间距）同步到 uView Pro 的
theme.scss，并在 Uno 配置中复用。
- 注意 UnoCSS 的解析规则可能会与 uView Pro 组件库内置样式冲突
注意事项：
- UnoCSS 从 v0.59 起只提供 ESM 支持，某些老旧构建环境需降级或额外配置；
- 在使用 apis 或小程序特性时，注意属性名与平台限制。
7. 插件组合示例（完整 vite.config.ts）
下面给出一个常见的 vite.config.ts 组合示例，展示如何把上面插件整合到同一个工程中：
import { fileURLToPath, URL } from "node:url";
import Uni from "@uni-helper/plugin-uni";
import Components from "@uni-helper/vite-plugin-uni-components";
import { uViewProResolver } from "@uni-helper/vite-plugin-uni-components/resolvers";
import UniLayouts from "@uni-helper/vite-plugin-uni-layouts";
import UniManifest from "@uni-helper/vite-plugin-uni-manifest";
import UniMiddleware from "@uni-helper/vite-plugin-uni-middleware";
import UniPages from "@uni-helper/vite-plugin-uni-pages";
import UniPlatform from "@uni-helper/vite-plugin-uni-platform";
import UniPlatformModifier from "@uni-helper/vite-plugin-uni-platform-modifier";
import UniRoot from "@uni-ku/root";
import UnoCSS from "unocss/vite";
import { defineConfig } from "vite";
export default defineConfig({
resolve: {
alias: {
"@": fileURLToPath(new URL("./src", import.meta.url)),
},
},
plugins: [
Components({
dts: true,
resolvers: [uViewProResolver()],
}),
UniPages(),
UniLayouts(),
UniManifest(),
UniPlatform(),
UniPlatformModifier(),
UniMiddleware(),
UniRoot(),
Uni(),
UnoCSS(),
],
});
8. 常见故障排查（针对插件集成）
- uni-pages 未识别页面：确认目录结构、文件后缀以及
pages.config.* 是否存在语法错误；
- uni-components 未按需引入：检查插件
dirs 配置与组件命名是否匹配，或手动添加 resolver；
- layouts 无效：确认页面是否使用
definePage({ layout: 'xxx' }) 或 pages.json 的 layout 配置被覆盖；
- manifest 生成错误：在本地构建时查看生成的
manifest.json，并在真机或云打包平台验证；
- UnoCSS 样式不生效：确认 UnoCSS 是否在 plugins 列表中且 preset 已正确加载；
- uView Pro 组件样式错乱：确认 UnoCss 解析规则是否与组件库存在冲突问题；
六、uView Pro Starter：开箱即用的项目模板
uView Pro Starter 是官方维护的快速启动模板，目前集成了 create-uni、uView Pro、UnoCSS 与 uni-helper 常用插件，适合作为企业或个人项目的起点。核心优势包括：
- 规范的项目结构与开发脚本；
- 预配置的 linter、格式化、TypeScript 与 Volar 支持；
- UnoCSS 和主题变量已集成，支持快速定制风格；
- 常用页面、布局、示例组件齐全，便于二次开发。
快速使用：
# 直接 clone
git clone https://github.com/anyup/uView-Pro-Starter.git
cd uView-Pro-Starter
pnpm install
pnpm run dev:h5
后面可以通过 create-uni 直接选择 uView Pro Starter 模板，目前还没建设完成。
Starter 的目的是把工程化、规范、常见实践都“开箱即用”，让团队把精力集中在业务实现上，而不是基础设施搭建。
七、uView Pro 与 uni-helper 的协同最佳实践（总结）
- 使用
uView Pro Starter 作为项目模板，默认预集成了大部分插件配置，能让团队开箱即用；
- 对于页面与组件的自动化引入，优先考虑
uni-pages + uni-components，降低重复维护成本；
- 在
uni-components 中为 u- 前缀做显式 resolver，避免与其他库冲突；
- 将 uView Pro 的主题变量与 UnoCSS 的设计 tokens 做映射，保证样式统一且可维护；
- 在 CI 中加入
pnpm install --frozen-lockfile、lint、typecheck 步骤，保证团队一致性；
- 做好平台差异化管理（合理使用
uni-platform）但尽量减少全平台分支，以降低维护成本。
八、注意事项
1. 样式、sass 与版本兼容建议
在实际项目中，sass 与 sass-loader 的版本兼容性常会引发样式构建问题。建议在团队内统一并锁定版本，减少“本地能跑、CI 失败”的尴尬。
推荐版本（uView Pro 社区实践验证）：
"sass": "1.63.2",
"sass-loader": "10.4.1"
同时，注意 uView Pro 的内部样式及主题文件采用 @import 形式引入。所以一定要注意 sass 的版本，
如使用 @use / @forward 语法引入 uView Pro 的样式文件，可能会导致样式丢失，报错，所以请使用 @import 引入。
2. TypeScript、Volar 与类型提示体验
uView Pro 自带 TypeScript 类型声明文件，结合 Volar 能获得良好的组件属性、事件、插槽的代码补全与类型校验。以下为推荐配置：
- 确保 VS Code 安装
Volar，并禁用 Vetur；
- 在
tsconfig.json 中添加：
{
"compilerOptions": {
"types": ["uview-pro/types"],
"skipLibCheck": true
}
}
- 在团队中统一
tsconfig 与 VS Code 推荐扩展配置（.vscode/extensions.json），减少“我的能提示你的不能提示”的现象。
3. 按需加载、tree-shaking 与打包优化
为减小包体积，建议：
- 优先按需导入工具函数与业务组件（避免全局引入全部组件），
- 使用 uni-helper 的
uni-components 或配合 Vite 的按需加载插件实现自动 tree-shaking，
- 对大型列表使用虚拟滚动、分页或懒加载，
- 在生产构建时开启压缩、静态资源缓存以及 CDN/边缘分发。
示例：按需引入工具函数
import { deepClone } from "uview-pro";
const copy = deepClone(obj);
4. 与其他组件库共存的注意事项
项目中若存在 uview-plus、uView 1.x、uView 2.x 或其他同类库，可能会出现 easycom 冲突、样式覆盖或工具命名冲突。解决建议：
- 在迁移期避免自动扫描多个组件库的同名规则；
- 调整
easycom.custom 规则，只指向 uview-pro 或具体库路径；
- 团队层面统一组件库选型，减少冲突成本。
5. 常见问题与排查清单
- 组件没有样式？→ 检查
theme.scss 或 index.scss 是否正确引入；
- easycom 无效？→ 检查
pages.json 的 custom 配置与路径；
- Volar 无补全？→ 禁用 Vetur、重启 VS Code、确认
tsconfig.json 设置；
- Sass 语法报错？→ 检查
sass 与 sass-loader 版本并统一锁定；
- 依赖冲突？→ 清理
node_modules / pnpm install --frozen-lockfile 并统一依赖来源。
更多常见问题请参考社区网站，实时更新：uviewpro.cn/zh/guide/fa…
九、uView Pro（为开源而生）
uView Pro 是一款免费、开源、面向个人和企业的组件库。希望通过 uView Pro Starter 与 create-uni 的结合，降低团队上手成本，提高项目启动速度。
同时欢迎企业与开发者在 GitHub / Gitee 提交 PR、Issue，参与组件优化、示例补全与文档改进。
项目地址：
十、结语：把时间交给业务，把基础交给 uView Pro
通过 create-uni + uView Pro + uni-helper 插件体系，你可以在极短的时间内搭建一个现代化、可维护、类型安全的 uni-app 项目。无论是单人项目、快速原型，还是企业级多团队协作，这套组合都能显著降低启动成本、提高开发效率。
所以，强烈建议你：
- 使用
uView Pro Starter，将其作为项目起点；或者使用 create-uni 创建新项目时选择包含 uView Pro 的模板；
- 合理使用
uni-helper 插件系统，减少重复工作；
- 在团队内推广统一模板与依赖锁定策略；
欢迎访问与关注：
登录