uview必须通过uni_modules机制安装并配置，不能仅用npm install；需放入uni_modules目录、正确配置easycom、按vue2/vue3差异注册、精准导入scss文件，缺一不可。
uView 不是 npm 包装完就能用的普通 UI 库，它必须走 uni_modules 插件机制或严格匹配的 npm 配置路径，否则 <u-button></u-button> 标签会白屏、控制台无报错、样式全丢——这是 90% 新手卡住的第一关。
确认项目类型和对应包名
Vue2（uni-app 2.x）和 Vue3（uni-app 3.x + Vite）用的是两个完全独立的包，混用必报错：
- Vue2 项目：必须装
uview-ui@2.0.38（不是最新版），import uView from 'uview-ui'才能通过 - Vue3 项目：必须装
uview-plus，import uViewPlus from 'uview-plus'，写成uview-ui直接报Cannot find module 'uview-ui' - 检查
node_modules下是否存在对应文件夹，不存在就重装；HBuilderX 用户建议直接从插件市场导入，自动生成uni_modules/uview-ui或uni_modules/uview-plus
main.js 或 main.ts 注册顺序不能错
注册时机和方式错了，组件内部逻辑（比如 uni.$u、this.$u）就失效：
- Vue2（
main.js）：import uView from 'uview-ui'必须在new Vue()之前，且不能放在App.vue的onLaunch里 - Vue3（
main.ts）：app.use(uViewPlus)必须是createSSRApp(App)创建后第一行use，如果后面还用了pinia或i18n，uViewPlus必须排最前 - TypeScript 项目记得在
shims-vue.d.ts加declare module 'uview-ui'或declare module 'uview-plus'，否则uni.$u类型丢失
pages.json 的 easycom 路径必须一字不差
easycom 是 <u-button></u-button> 能直接写的唯一依赖，配错就白屏，且控制台不报错：
- Vue2：
"^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"—— 注意开头没@/，斜杠必须是正斜杠/ - Vue3：
"^u-(.*)": "uview-plus/components/u-$1/u-$1.vue"—— 同样不能有反斜杠\，Windows 复制容易带入，要手动改 - 该字段必须放在
pages.json的顶层对象下，不能嵌在"h5"、"mp-weixin"或"subNVues"里 - 改完必须重启 HBuilderX 或重新运行
npm run dev:mp-weixin，热更新不触发扫描
SCSS 导入位置和顺序是样式生效的关键
uni-app 对 App.vue 的 <style lang="scss"></style> 解析极其敏感，错一行就全乱：
-
App.vue的<style lang="scss"></style>标签内，@import必须是第一行，前面不能有空行、注释、空格 - Vue2 写
@import "uview-ui/index.scss";，Vue3 写@import "uview-plus/index.scss";，路径错一个字符就无样式 -
uni.scss中的@import 'uview-ui/theme.scss'是可选的，只影响主题变量（如$u-primary-color），删了不影响按钮渲染，但App.vue里的index.scss绝对不能少
最容易被忽略的是：所有配置都正确，但没重启开发服务，uni_modules 和 easycom 就不会被重新加载；还有 Windows 用户复制路径时带入反斜杠，正则直接失效。这些地方没报错，但整个 UI 就是空白——问题不在代码，在构建流程本身。
