10 分钟上手：create-uni + uView Pro 快速搭建企业级 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 文件）
  • 选择需要的库时勾选必要的库：
    • Pinia
    • Unocss
  • 选择 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";

exportfunction 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 插件市场：https://ext.dcloud.net.cn/plugin?id=24633

在 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 的配合要点以及常见注意事项。

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";

exportdefault 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>
  • 在页面中指定布局（definePage）：
    <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";

exportdefault 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";

exportdefault 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 能获得良好的组件属性、事件、插槽的代码补全与类型校验。以下为推荐配置：

  1. 确保 VS Code 安装 Volar，并禁用 Vetur；
  2. 在 tsconfig.json 中添加：
    {
"compilerOptions": {
 "types": ["uview-pro/types"],
 "skipLibCheck": true
}
}
  3. 在团队中统一 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 并统一依赖来源。

更多常见问题请参考社区网站，实时更新：https://uviewpro.cn/zh/guide/faq.html

九、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 插件系统，减少重复工作；
  • 在团队内推广统一模板与依赖锁定策略；

欢迎访问与关注：

作者：Jeebiz  创建时间：2025-10-19 11:27
最后编辑：Jeebiz  更新时间：2025-10-19 11:52