uni-app 项目创建方式有哪些，看这一篇就够了！

本篇文章全面梳理 uni-app 项目的主流创建方式（HBuilderX 与 CLI），涵盖 Vue2 与 Vue3 技术栈，并详细说明如何高效引入 uView Pro 组件库。帮助 uni-app 开发者快速上手与避坑。

一、uni-app 项目创建方式概览

uni-app 作为主流的跨端开发框架，支持多种项目创建方式，主要分为：

HBuilderX 可视化创建（适合初学者、快速原型、企业团队）
CLI 命令行创建（适合进阶开发者、自动化、团队协作）

同时，uni-app 支持 Vue2 与 Vue3 两种技术栈，开发者可根据项目需求选择。

HBuilderX：官方 IDE 下载地址

VSCode：官方 IDE 下载地址

二、HBuilderX 方式创建 uni-app 项目

1. HBuilderX 简介

HBuilderX 是 DCloud 官方推出的可视化 IDE，集成 uni-app 项目模板、插件市场、云打包等功能，适合零基础和企业团队。

2. 创建流程

打开 HBuilderX，点击"文件"→"新建"→"项目"
选择"uni-app 项目"，填写项目名称、路径
选择技术栈（Vue2 或 Vue3，部分版本需手动切换）
完成创建，自动生成项目结构

3. Vue2 与 Vue3 项目区别

Vue2 项目：兼容性好，生态成熟，适合老项目或对兼容性要求高的场景
Vue3 项目：性能更优，支持 Composition API、TS 类型提示，推荐新项目优先选择

4. 项目结构说明

pages/：页面文件夹
components/：自定义组件
uni_modules/：第三方模块（如 uView Pro）
static/：静态资源
main.js/main.ts：入口文件
pages.json：路由与 easycom 配置

三、CLI 方式创建 uni-app 项目

1. CLI 简介

CLI（Command Line Interface）方式适合进阶开发者，支持自动化、版本管理、团队协作，便于集成 CI/CD。

2. 创建流程

创建 vue3 项目，支持创建 JavaScript\TypeScript 两种开发方式

创建以 JavaScript 开发的工程

bash 复制代码

npx degit dcloudio/uni-preset-vue#vite my-vue3-project

创建以 TypeScript 开发的工程

bash 复制代码

npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-ts-project

创建 vue2 项目

需要全局安装 vue-cli npm install -g @vue/cli

bash 复制代码

vue create -p dcloudio/uni-preset-vue my-vue2-project

经验总结：Vue 2 项目，建议使用以下命令直接进行创建，node 版本不要过高

建议使用 @vue/cli@4.5.14 创建，其他版本可能会有问题

bash 复制代码

npx @vue/cli@4.5.14 create -p dcloudio/uni-preset-vue my-vue2-project

还可以通过 colorful uniapp cli 创建，仅支持创建 Vue2 项目，默认集成 uView 1.8.8 组件库。

bash 复制代码

pnpm create colorful-app

根据上面创建项目完成后，进入项目目录，安装依赖：

bash 复制代码

cd my-project
npm install

启动项目：

bash 复制代码

npm run dev:mp-weixin # 启动微信小程序
npm run dev:h5        # 启动H5

更多运行命令以及自定义命令参考 package.json 文档

3. Vue2 与 Vue3 项目选择

CLI 支持通过不同命令创建 Vue2 或 Vue3 模板，简便快捷
Vue3 项目推荐配合 Vite 构建，性能更优
Vue2 项目兼容性好，适合维护老项目，新项目优先 Vue3

4. 项目结构说明

src/：源码目录
pages/、components/、uni_modules/等结构与 HBuilderX 类似
package.json：依赖与脚本管理
tsconfig.json：TypeScript 配置（Vue3 项目推荐）

注意

Vue3/Vite 版要求 node 版本 18+、20+
如果使用 HBuilderX（3.6.7 以下版本）运行 Vue3/Vite 创建的最新的 cli 工程，需要在 HBuilderX 运行配置最底部设置 node 路径为自己本机高版本 node 路径（注意需要重启 HBuilderX 才可以生效）
如果使用 CLI 创建的 uni-app 工程，可以通过一些工具来管理多个 node 版本，比如：nvm，volta，fnm 等 node 版本管理工具。

四、通过 unibest cli 创建 uni-app 项目

unibest 应该是目前最火的 uni-app 脚手架，它是菲鸽大佬联同众多 uni-app 大佬开发的 uni-app 框架，集成了最新技术栈和开发工具。

通过 create-unibest 脚手架快速创建项目：

bash 复制代码

pnpm create unibest@latest <项目名>
# 或交互式创建
pnpm create unibest@latest

可以直接选择 base-uview-pro 模板即可获得基于 uview-pro 组件库的项目结构，所有相关配置已经集成好。

bash 复制代码

pnpm install
# 运行 H5
pnpm dev:h5
# 运行微信小程序
pnpm dev:mp-weixin

更多关于 unibest + uView Pro 使用可参考：# 2025 最推荐的 uni-app 技术栈：unibest + uView Pro 高效开发全攻略

五、引入组件库 uView Pro

选择 uView Pro 作为 uni-app 生态主流 UI 组件库，目前支持 HBuilderX 与 CLI 两种安装方式，仅 Vue3 项目，因为 Vue2 你可以安装 uView UI 1.x 或 2.x 的组件库。

通过 unibest 创建的 base-uview-pro 项目可以略过这一步。

1. HBuilderX 项目引入 uView Pro

（1）通过插件市场安装

打开 HBuilderX，进入"插件市场"
搜索"uView Pro"，点击"安装到项目"
安装完成后，uView Pro 自动加入 uni_modules 目录

（2）手动导入 uni_modules

下载 uView Pro 源码，复制到项目的 uni_modules 目录
在 pages.json 配置 easycom 自动引入：

json 复制代码

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

在 main.js/main.ts 全局引入 uView Pro（部分场景可省略）
全局引入主题样式：

js 复制代码

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

（3）npm 安装

通过 HuilderX 创建的 uni-app 项目，也可以通过 npm 安装 uView Pro，然后全局引入即可。具体参考下述步骤

（4）Vue2 与 Vue3 兼容说明

uView Pro 主力支持 Vue3，不支持 Vue2
Vue2 项目建议使用 uView UI 1.x 或 2.x 或升级至 Vue3 使用 uView Pro
Vue3 项目可享受 TS 类型提示、Volar 智能补全

2. CLI 项目引入 uView Pro

（1）通过 npm 安装

在项目根目录执行：
bash 复制代码
```
npm install uview-pro --save
```

在 main.ts 全局注册 uView Pro：

js 复制代码

import { createSSRApp } from "vue";
import uViewPro from "uview-pro";

export function createApp() {
  const app = createSSRApp(App);
  app.use(uViewPro);
  return {
    app,
  };
}

配置 easycom 自动引入：

json 复制代码

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

引入全局样式在 uni.scss 中引入主题样式：

scss 复制代码

@import 'uview-pro/theme.scss';
在 App.vue 首行引入基础样式：

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

scss 复制代码

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

按需引入组件与工具函数，享受 tree-shaking 与类型提示

更多内容参考官方文档：uView Pro 官方文档

（2）Vue2 与 Vue3 兼容说明

Vue3 项目推荐配合 Vite 与 TypeScript，享受最佳开发体验
uView Pro 同样不支持 Vue2，强烈建议升级至 Vue3

3. uView Pro 类型提示与 Volar 支持

（1）TypeScript 类型声明

uView Pro 内置完整 TS 类型声明，支持属性、事件、插槽、工具函数等智能补全

Vue3 项目在 tsconfig.json 添加：

json 复制代码

{
  "compilerOptions": {
    "types": ["uview-pro/types"]
  }
}

通过 uni_modules 本地引入的 uview-pro ，自动全局引入 TS 类型声明，部分场景可补充 typeRoots
HBuilderX 项目一般无需配置，不支持

（2）Volar 插件配置

推荐在 VSCode 安装 Volar 插件，禁用 Vetur
享受全局组件类型提示、错误校验、代码跳转

六、常见问题与避坑建议

依赖冲突：npm 与 uni_modules 安装方式不可混用，二选一。
组件样式异常：检查 theme.scss 引入与 easycom 配置。
类型提示缺失：确认 tsconfig.json 与 Volar 插件配置。
Sass 语法报错：推荐锁定"sass": "1.63.2"、"sass-loader": "10.4.1"，避免语法不兼容。
与其他组件库冲突：避免同项目引入 uview-plus、colorui 等同名组件库。
Vue2 项目兼容性：优先升级至 Vue3，享受更优生态与类型支持。
团队协作：统一依赖版本与配置，定期代码审查。

七、总结

uni-app 项目创建方式灵活，HBuilderX 适合快速原型与企业协作，CLI 适合自动化与进阶开发。uView UI 组件库作为生态明星，而 uView Pro 是继 uView UI 之后全面重构的 Vue3 组件库，支持完整的 TS 类型提示及校验，支持多种引入方式，助力高效开发与团队协作。

推荐资源：

如有更多问题，欢迎查阅官方文档、社区 Issue 或加入交流群共同进步！

欢迎 Star、Fork、PR、Issue 支持与反馈。