uView在uni-app中需完成四步配置：①main.js/ts正确注册（Vue2用Vue.use，Vue3用createSSRApp().use且须最先调用）；②pages.json启用easycom并配对路径；③App.vue和uni.scss按序引入SCSS样式文件并加lang="scss"；④Vue3项目还需在vite.config.js中配置optimizeDeps.include和scss.additionalData。
uView 在 uni-app 中不能“装完就用”，必须完成四步基础配置，缺一不可；否则运行时报 Unknown custom element 或样式错乱，尤其是 Vue3 项目容易卡在 app.use() 调用方式和 vite.config.js 预构建上。
main.js 或 main.ts 中正确注册 uView 实例
Vue2 项目直接在 main.js 中 import 并 Vue.use()；Vue3（尤其 Vite + Composition API）必须用 createSSRApp().use() 方式，且 uview-plus 的 app.use() 必须放在所有其他插件（如 i18n、pinia）之前。
- Vue2 写法（
main.js）：import uView from '@/uni_modules/uview-ui' Vue.use(uView)
- Vue3 + Vite 写法（
main.ts）：import { createSSRApp } from 'vue' import uViewPlus from 'uview-plus' export function createApp() { const app = createSSRApp(App) app.use(uViewPlus) // 注意：必须最先调用 return { app } } - 常见错误：在 Vue3 项目中仍写
Vue.use()→ 报Cannot read property 'use' of undefined - 注意顺序：若同时用了
vue-i18n@v9，app.use(uViewPlus)必须在app.use(i18n)之前，否则 i18n 的legacy: false会干扰 uView 的内部逻辑
pages.json 中必须启用 easycom 组件自动导入
uView 的组件（如 <u-button></u-button>）不手动 import 就能用，全靠 easycom 规则匹配。漏配或路径写错，页面里写对了标签也渲染不出，控制台无报错但空白。
- 正确配置位置：项目根目录
pages.json的顶层对象内（不是subNVues或tabBar下） - Vue2 / uView 2.x 对应规则：
"easycom": { "^u-(.*)": "@/uni_modules/uview-ui/components/u-$1/u-$1.vue" } - Vue3 / uView Plus 对应规则：
"easycom": { "^u-(.*)": "uview-plus/components/u-$1/u-$1.vue" } - 关键点：路径中的斜杠方向必须是正斜杠
/，Windows 下复制反斜杠\会导致匹配失败 - 验证方法：删掉该配置，重启 HBuilderX 或运行
npm run dev:mp-weixin，<u-button></u-button>立刻变白屏
样式文件三处导入缺一不可且位置敏感
uView 的样式分三层：基础结构（index.scss）、主题变量（theme.scss）、全局覆盖（uni.scss 引入的预设）。任意一处漏、顺序错、lang 属性没加，都会导致按钮无边框、图标不显示、颜色全灰。
-
App.vue中第一行<style lang="scss"></style>内引入：@import "@/uni_modules/uview-ui/index.scss";
（Vue2）或@import "uview-plus/index.scss";
（Vue3） -
uni.scss中引入主题变量：@import "@/uni_modules/uview-ui/theme.scss";
（Vue2）或@import "uview-plus/theme.scss";
（Vue3） - 必须加
lang="scss"：没加则 SCSS 语法（如@import、变量）被忽略，退化为纯 CSS 解析 → 全部样式失效 - 顺序不能颠倒：
App.vue的index.scss必须在最前，它依赖theme.scss定义的变量；uni.scss的theme.scss必须在其他自定义样式之前，否则你的重写会被 uView 覆盖
Vue3 项目额外要处理 vite.config.js
Vue3 + Vite 环境下，uView Plus 的组件含大量 defineComponent 和 setup()，不显式预构建会触发热更新异常、HMR 失效、甚至开发服务器卡死。
- 必须在
vite.config.js的optimizeDeps.include中加入：include: ['uview-plus']
- SCSS 变量需全局注入：在
css.preprocessorOptions.scss.additionalData中补全：additionalData: '@import "uview-plus/theme.scss";'
- 漏掉
optimizeDeps.include的典型现象：首次启动正常，修改App.vue后保存，控制台反复打印[vite] hot updated: /src/App.vue却无实际刷新，必须手动刷新浏览器 - 注意：HBuilderX 自带的编译器不读
vite.config.js，所以 Vue3 项目务必用 CLI 启动（npm run dev:mp-weixin），否则配置无效
最容易被跳过的其实是 easycom 的路径拼写和 vite.config.js 的 optimizeDeps —— 前者让组件“看不见”，后者让开发过程“动不了”。配完别急着写业务，先放一个 <u-button></u-button> 和 <u-icon name="star"></u-icon> 在首页，连点三次保存看是否稳定渲染。
