必须npm安装并按需引入，CDN无效；Vue 3用@next版，Vue 2用1.x版；禁用全局注册和easycom；按需引入需区分Vue版本路径；uni-datetime-picker值须为毫秒时间戳；微信小程序需在App.vue中兜底CSS变量并注意popup双向绑定差异。
必须 npm 安装 + 按需引入，CDN 或 script 标签完全无效；装错版本或漏 import 会导致 <uni-badge></uni-badge> 报 Unknown custom element。
npm 安装和版本必须严格对齐
Vue 3 项目执行：npm install @dcloudio/uni-ui@next；Vue 2 项目必须锁定：npm install @dcloudio/uni-ui@1.x。pnpm/yarn 在部分 HBuilderX 版本中存在路径解析异常，优先用 npm。
- 安装后检查
node_modules/@dcloudio/uni-ui是否存在，且目录下有dist和components - 全局注册
Vue.use(uniUI)会把所有组件打进首屏 JS，体积飙升，禁用 - easycom（输入
u自动补全）依赖 uni_modules 目录结构和编译扫描，路径误删或未导入时静默失效，不可靠
按需引入写法（Vue 3 和 Vue 2 差异明显）
在页面或组件的 <script></script> 中显式 import 并注册：
- Vue 3：
import { uniBadge, uniDatetimePicker } from '@dcloudio/uni-ui'，再在components: { uniBadge, uniDatetimePicker }中注册 - Vue 2：
import uniBadge from '@dcloudio/uni-ui/lib/uni-badge/uni-badge.vue'（注意路径带lib/），再注册 -
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 单向属性。
- Vue 3 写法：
<uni-popup v-model:show="popupVisible"></uni-popup> - Vue 2 写法：
<uni-popup :show="popupVisible"> popupVisible = val"></uni-popup> -
v-if会破坏mounted后的 DOM 操作，导致内容空白或点击无响应 - 弹窗内含
<input>时，务必加focus或绑定ref，否则键盘可能不弹出
最常被忽略的是：CSS 变量兜底必须写在 App.vue 的 <style></style> 里，且 uni-popup 的双向绑定写法在 Vue 2/Vue 3 中完全不同，混用就会静默失效。
