使用 uni-ui 需 npm 安装并按需引入：Vue 3 用 @dcloudio/uni-ui@next，Vue 2 锁定 @dcloudio/uni-ui@1.x；禁用全局注册和 easycom，须 import 组件并显式注册；注意微信小程序 CSS 变量兼容、时间戳格式、focus/ref 触发键盘及基础库版本校验。
直接用 uni-ui 就能快速搭出标准 UI，但必须走 npm 安装 + 按需引入，CDN 或 script 标签引入完全无效。
npm 安装和版本对齐是前提
不装包或装错版本，<uni-badge></uni-badge> 这类标签会直接报 Unknown custom element。Vue 3 项目要装 @dcloudio/uni-ui@next（当前默认），Vue 2 项目必须锁定 @dcloudio/uni-ui@1.x。pnpm/yarn 在部分 HBuilderX 版本里有路径解析异常，优先用 npm。
- 执行命令：
npm install @dcloudio/uni-ui - 安装后检查
node_modules/@dcloudio/uni-ui是否存在，且目录下有dist和components - 不要全局注册：
Vue.use(uniUI)会导致所有组件打进首屏 JS，体积飙升
按需引入比 easycom 更可控
HBuilderX 的 easycom（输入 u 自动补全）虽方便，但依赖 uni_modules 目录结构和编译时扫描，一旦组件未正确导入或路径被误删，就会静默失效。按需 import + components 注册更明确、可调试。
- 在页面中写：
import { uniBadge, uniDatetimePicker } from '@dcloudio/uni-ui' - 注册进组件：
components: { uniBadge, uniDatetimePicker } -
uni-datetime-picker的value必须传毫秒时间戳，传字符串或秒级时间会不响应
微信小程序 CSS 变量兼容性必须手动兜底
uni-ui 默认用 --uni-color-primary 等 CSS 变量控制主题，但微信小程序基础库
- 打开微信开发者工具 → 「详情」→「项目设置」，确认基础库 ≥ 2.27.0
- 若无法升级（如需兼容老用户），必须在
App.vue的<style></style>中加:root声明，例如：--uni-color-primary: #007aff - 别在
uni.scss里覆盖变量 —— 它只影响编译期，不作用于运行时 CSS 变量
uni-popup 的显隐逻辑最容易踩坑
它不是普通组件，不能靠 v-if 控制挂载，也不能只传 :show 单向属性。内部依赖 mounted 后的 DOM 操作，v-if 会破坏生命周期，导致内容空白或点击无响应。
- Vue 3 写法：
<uni-popup v-model:show="popupVisible"></uni-popup> - Vue 2 写法：
<uni-popup :show="popupVisible"> popupVisible = val"></uni-popup> - 弹窗内含
<input>时，务必加focus或绑定ref，否则键盘可能不弹出
最常被忽略的是：微信基础库版本检查和 uni-popup 的双向绑定强制要求。这两点不处理，其他都白搭。
