🔥开源零配置！10 分钟上手：create-uni + uView Pro 快速搭建企业级 uni-app 项目

一、为什么选择 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 工具链或插件市场，非必要不使用）

确保全局工具可用：

bash 复制代码

# 建议使用 pnpm
npm install -g pnpm
# 若需要全局安装脚手架（可选）
npm install -g @dcloudio/uni-app

三、使用 create-uni 快速创建项目（一步到位）

create-uni 是一套现代化脚手架，支持选择模板、快速集成 uView Pro 组件库等，下面给出用 pnpm create 的推荐流程：

bash 复制代码

# 使用 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 项目）

bash 复制代码

pnpm add uview-pro
# 或者 npm install uview-pro --save

在 Vue3 项目中，全局引入并注册：

js 复制代码

// 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 中引入主题：

scss 复制代码

@import "uview-pro/theme.scss";

在 App.vue 首行引入基础样式：

html 复制代码

<style lang="scss">
  @import "uview-pro/index.scss";
</style>

在 pages.json / vite 的 easycom 配置中添加：

json 复制代码

"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全局引入并注册

javascript 复制代码

// 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：

json 复制代码

"easycom": {
  "autoscan": true,
  "custom": {
    "^u-(.*)": "@/uni_modules/uview-pro/components/u-$1/u-$1.vue"
  }
}

在 uni.scss 中引入主题：

scss 复制代码

@import "@/uni_modules/uview-pro/theme.scss";

在 App.vue 首行引入基础样式：

html 复制代码

<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 等虚拟模块用于在代码中读取页面信息，便于构建菜单、统计或自动化文档。

安装：

bash 复制代码

pnpm add -D @uni-helper/vite-plugin-uni-pages

基本配置（vite.config.ts）：

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）：

ts 复制代码

import { defineUniPages } from "@uni-helper/vite-plugin-uni-pages";

export default defineUniPages({
  pages: [],
  globalStyle: {
    navigationBarTextStyle: "black",
    navigationBarTitleText: "MyApp",
  },
  subPackages: [],
});

在代码中获取页面元数据：

ts 复制代码

/// <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 的全局扫描，减少启动扫描成本并提升按需加载精度；
支持自定义规则、扩展第三方组件库的映射。

安装：

bash 复制代码

pnpm add -D @uni-helper/vite-plugin-uni-components

配置示例，已经支持 uView Pro Resolver：

ts 复制代码

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 并将页面包裹在指定布局下，简化头部/尾部/侧边栏等公共区域维护。

安装：

bash 复制代码

pnpm add -D @uni-helper/vite-plugin-uni-layouts

配置示例：

ts 复制代码

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 中定义布局：

vue 复制代码

<template>
  <div class="layout">
    <slot name="header">默认头部</slot>
    <slot>主内容</slot>
    <slot name="footer">默认底部</slot>
  </div>
</template>

在页面中指定布局（definePage）：

vue 复制代码

<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，并支持按平台差异化配置。

安装：

bash 复制代码

pnpm add -D @uni-helper/vite-plugin-uni-manifest

配置示例：

ts 复制代码

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：

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 等，构建时自动替换为对应平台文件；
便于按平台做差异化实现，同时保持统一的项目结构与代码管理。

安装：

bash 复制代码

pnpm add -D @uni-helper/vite-plugin-uni-platform

配置示例：

ts 复制代码

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 的即时编译，开发体验流畅。

安装：

bash 复制代码

pnpm add -D @uni-helper/unocss-preset-uni unocss unocss-applet

vite 配置示例：

ts 复制代码

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 配置

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 组合示例，展示如何把上面插件整合到同一个工程中：

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 和主题变量已集成，支持快速定制风格；
常用页面、布局、示例组件齐全，便于二次开发。

快速使用：

bash 复制代码

# 直接 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 社区实践验证）：

json 复制代码

"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 中添加：

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/边缘分发。

示例：按需引入工具函数

ts 复制代码

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

欢迎访问与关注：

uView Pro 官网：uviewpro.cn/
Uni Helper 官网： uni-helper.js.org/
Github Star 与贡献： github.com/anyup/uview...
Gitee Star 与贡献： gitee.com/anyup/uview...
uView Pro Starter 模板： github.com/anyup/uView...
交流沟通：uviewpro.cn/zh/resource...