npm安装+按需引入是唯一可靠方式：vue3用@next，vue2锁定1.x；微信小程序需基础库≥2.27.0并手动声明css变量，uni-popup必须双向绑定。
直接 npm 安装 + 按需引入是唯一可靠方式，cdn、script 标签、easycom 自动补全都容易静默失效或体积失控。
npm 安装必须对齐 Vue 版本
装错版本会导致 <uni-badge></uni-badge> 这类标签报 Unknown custom element 错误：
- Vue 3 项目：执行
npm install @dcloudio/uni-ui@next（当前默认） - Vue 2 项目：必须锁定
npm install @dcloudio/uni-ui@1.x，用@next会直接不兼容 - pnpm 或 yarn 在部分 HBuilderX 版本中存在路径解析异常，优先用 npm
- 安装后检查
node_modules/@dcloudio/uni-ui下是否存在dist和components目录
按需引入比 easycom 更可控
easycom（如输入 u 自动补全）依赖 uni_modules 目录结构和编译扫描，一旦路径被误删或插件未正确导入，组件就静默不渲染，且无法调试：
- 在页面或组件中显式
import：例如import uniBadge from '@dcloudio/uni-ui/lib/uni-badge/uni-badge.vue' - 在
components选项中注册：components: { uniBadge } - 模板中使用：
<uni-badge text="1"></uni-badge> - 禁用全局注册（
Vue.use(uniUI)），否则所有组件都会打进首屏 JS，体积飙升
微信小程序 CSS 变量和时间戳必须手动兜底
uni-ui 默认依赖 CSS 自定义变量（如 --uni-color-primary）和毫秒级时间戳，这两点在微信小程序上最容易出问题：
- 微信基础库必须 ≥ 2.27.0：打开微信开发者工具 → 「详情」→「项目设置」确认版本；若无法升级，需在
App.vue的<style></style>中手动声明：:root { --uni-color-primary: #007aff; }（别写在uni.scss，它只影响编译期） -
uni-datetime-picker等组件的value必须传毫秒时间戳，传字符串（"2026-05-31"）或秒级时间（1748714000）会导致不响应
uni-popup 的双向绑定是硬性要求
它不是普通组件，不能靠 v-if 控制挂载，也不能只传单向 :show：
- Vue 3 写法必须用
v-model:show：<uni-popup v-model:show="popupVisible"></uni-popup> - Vue 2 写法必须配对绑定：
<uni-popup :show="popupVisible" false></uni-popup> - 弹窗内含
<input>时，务必加focus属性或绑定ref，否则键盘可能不弹出 -
v-if会破坏其内部 mounted 后的 DOM 操作逻辑，导致内容空白或点击无响应
最常被跳过的两件事：检查微信基础库版本、强制用双向绑定控制 uni-popup。其他配置全对，这两点没做，组件照样不工作。
