uni-app：Vue 跨端框架安装与微信小程序运行指南

uni-app 是 DCloud 公司开源的、使用 Vue.js 开发所有前端应用的框架。开发者编写一套代码，可发布到 iOS、Android、鸿蒙、Web（响应式），以及微信/支付宝/百度/抖音/飞书/QQ/快手/钉钉/淘宝/京东/小红书等各种小程序、快应用、鸿蒙元服务等多个平台。

一、项目官方信息

uni-app 分两代：uni-app（老一代，App 引擎逻辑层用 JS、渲染层用 web-view）；uni-app x（新一代主分支，蒸汽模式，App 平台原生渲染，Android/iOS/鸿蒙渲染速度是原生 2~3 倍）。

二、官方图片

一套代码运行到多个平台：

实际运行效果：

三、环境要求

• 推荐 HBuilderX（DCloud 官方 IDE，开箱即用）。
• 或 CLI 方式：Node.js 16+。
• 微信开发者工具（用于微信小程序预览）。
• 微信小程序 AppID。

四、完整部署/接入步骤

1. 方式一：HBuilderX（推荐新手）

1. 下载并安装 HBuilderX：https://www.dcloud.io/hbuilderx.html ；
2. 菜单「文件 → 新建 → 项目」；
3. 选择「uni-app」，填入项目名，选择 Vue 版本（vue2/vue3），模板选「默认模板」；
4. 点击「运行 → 运行到小程序模拟器 → 微信开发者工具」；
5. 首次运行会提示配置微信开发者工具路径，按引导完成。

2. 方式二：CLI 创建

npx degit dcloudio/uni-preset-vue#vite my-uni-app
cd my-uni-app
npm install

运行到微信小程序：

npm run dev:mp-weixin

产物输出到 dist/dev/mp-weixin，用微信开发者工具导入该目录。

3. 用微信开发者工具打开

打开微信开发者工具，导入项目，目录指向 unpackage/dist/dev/mp-weixin（HBuilderX）或 dist/dev/mp-weixin（CLI），填入 AppID。

4. 生产打包

HBuilderX：菜单「发行 → 小程序-微信」。 CLI：

npm run build:mp-weixin

五、使用方法

目录结构（CLI 模板）

my-uni-app/
├── src/
│   ├── pages/           # 页面
│   ├── static/          # 静态资源
│   ├── App.vue         # 应用入口
│   ├── main.js
│   ├── pages.json      # 页面路由
│   └── uni.scss        # 全局样式变量
└── package.json

配置页面

pages.json：

{
  "pages": [
    { "path": "pages/index/index" }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app"
  }
}

跨端能力

一套代码同时运行到微信、支付宝、百度、抖音、QQ、Web、iOS、Android、鸿蒙等；条件编译语法区分平台：

<!-- #ifdef MP-WEIXIN -->
<view>仅微信小程序显示</view>
<!-- #endif -->

uni-app x

新一代版本使用 uts 开发，uts 在 Android 编译为 Kotlin、iOS 编译为 Swift、鸿蒙编译为 ArkTS、Web/小程序编译为 JS。

六、常见问题 FAQ

1. 运行到微信小程序提示找不到微信开发者工具？ 在 HBuilderX 菜单「工具 → 设置 → 运行配置」里指定微信开发者工具安装路径；CLI 方式在微信开发者工具「设置 → 安全设置」开启服务端口。

2. CLI 产物在哪个目录？ dist/dev/mp-weixin（开发）或 dist/build/mp-weixin（生产）。

3. vue2 还是 vue3？ 新项目推荐 vue3（vite 模板）；uni-app x 主分支用 vue3 + uts。

4. 如何用条件编译区分平台？ 用 <!-- #ifdef MP-WEIXIN -->、<!-- #ifdef H5 --> 等注释包裹平台专属代码。

5. 示例代码在哪里？ hello uni-app 示例：https://github.com/dcloudio/hello-uniapp 。

6. 如何上架小程序？ CLI npm run build:mp-weixin 生成生产包，在微信开发者工具点「上传」，到公众平台提交审核。

七、跳转链接

• GitHub 仓库：https://github.com/dcloudio/uni-app
• 官方文档：https://doc.dcloud.net.cn/uni-app/
• HBuilderX 下载：https://www.dcloud.io/hbuilderx.html
• 示例：https://github.com/dcloudio/hello-uniapp
• 性能评测：https://github.com/dcloudio/uni-app/benchmark/vapor-benchmark-android.md