下面给你 vue-cli 模式下安装 uni-ui 的最详细步骤教程（从 0 到能使用），无坑可避坑，直接能跑。

✅ vue-cli 模式下安装 uni-ui 的详细过程

⚠️ 前提说明：
uni-ui 虽然是 uni-app 官方 UI 组件库，但 任何基于 Vue 的项目都可以使用，包括 Vue CLI、Vite、Nuxt 等。
但只有在 uni-app 项目 中（HBuilderX 或 vue-cli 模式）才能自动适配小程序、H5、App 等平台。

📌 一、准备环境

你的项目应当是 使用 vue-cli 创建的 uni-app 项目：

vue create -p dcloudio/uni-preset-vue my-uni-app

如果你已经有一个项目，可跳过。

📌 二、安装 uni-ui（方式一：npm 安装）— 推荐

在项目根目录执行：

npm i @dcloudio/uni-ui

或使用 yarn：

yarn add @dcloudio/uni-ui

📌 三、自动按需加载（最推荐方式）

安装插件：

npm i -D @dcloudio/uni-ui-nvue-styler

然后在 main.js 引入：

import Vue from 'vue'
import App from './App'

import uni from '@dcloudio/uni-ui'
Vue.use(uni)

new Vue({
  ...App
}).$mount()

Done！

📌 四、手动按需引入组件（可选）

比如使用 uni-button：

import uniButton from '@dcloudio/uni-ui/lib/uni-button/uni-button.vue'

export default {
  components: {
    uniButton
  }
}

模板中直接使用：

<uni-button type="primary">按钮</uni-button>

📌 五、支持自动组件扫描（uni-app 内置功能）

uni-ui 属于官方组件，不需要额外配置插件，编译器会自动识别。

例如你在页面中直接写：

<template>
  <view>
    <uni-card title="标题" extra="更多">
      内容内容内容
    </uni-card>
  </view>
</template>

不需要 import，编译器会直接帮你引入。

📌 六、HBuilderX 与 vue-cli 区别（重点）

功能vue-cli 模式HBuilderX 模式
uni-ui 引入方式需要安装 npm 包打开插件即可
是否自动按需引入✔️ 支持✔️ 内置
需不需要 import不需要（编译器自动处理）不需要

📌 七、测试是否安装成功

随便创建一个页面：pages/index/index.vue

<template>
  <view class="content">
    <uni-section title="测试 uni-ui" sub-title="这是第一段" type="line"></uni-section>

    <uni-card title="卡片标题" extra="更多">
      Hello uni-ui！
    </uni-card>

    <uni-button type="primary">主按钮</uni-button>
  </view>
</template>

运行：

npm run dev:%PLATFORM%

例如：

npm run dev:mp-weixin
npm run dev:h5

看到组件正常显示，即成功。

📌 八、常见问题（必看）

❗1. 提示组件未找到

原因：没有安装 @dcloudio/uni-ui
解决：

npm i @dcloudio/uni-ui

❗2. 小程序端报 “Component is not found”

请检查：
pages.json 是否正确配置页面。

❗3. 使用 nvue 时样式不生效

执行：

npm i -D @dcloudio/uni-ui-nvue-styler

并重启项目。

📌 九、完整示例 Demo

给你一个最小可运行示例：

<template>
  <view>
    <uni-card title="欢迎" extra="更多">
      uni-ui 在 vue-cli 模式成功运行！
    </uni-card>

    <uni-button type="primary" @click="handleClick">
      点击测试
    </uni-button>
  </view>
</template>

<script>
export default {
  methods: {
    handleClick() {
      uni.showToast({
        title: "成功",
        icon: "success"
      })
    }
  }
}
</script>

🎉 总结

你只需要：

  1. npm install @dcloudio/uni-ui
  2. 在页面中直接使用 <uni-xxx> 标签

就能在 vue-cli 模式的 uni-app 中使用全部 uni-ui 组件。