uni-app 的 easycom 未生效是因为需同时满足 components 目录结构规范与显式配置 easycom，常见原因包括目录位置错误、命名不合规、平台配置缺失或正则匹配不当。
uni-app 的 easycom 为什么没生效
easycom 不是“写了就自动引入”，它依赖 components 目录结构 + easycom 配置双满足。常见现象是组件写了、路径也对，但编译后报 Unknown custom element 错误。
实操建议：
- 确认
pages.json或vue.config.js（H5端）里已开启easycom：H5/小程序平台需在vue.config.js中配configureWebpack.chainWebpack；App端和微信小程序则默认支持，但必须启用compilerOptions.easycom（新版 uni-app 3.0+ 推荐统一在vue.config.js或vue.config.ts中显式配置） -
components目录必须位于项目根目录下（即与pages同级），且子目录名不能以__或.开头（如components/__base或components/.utils会被跳过） - 组件文件名必须符合 PascalCase（如
MyButton.vue），且文件内name选项要匹配（否则 H5 端可能 fallback 到全局注册逻辑失败）
easycom 的匹配规则怎么写才不踩坑
easycom 默认只匹配 components/**/*.{vue,tsx}，但你可以用正则自定义范围。问题常出在“想排除某些组件却误删了全部”或“用了通配却没生效”。
实操建议：
- 匹配所有组件：配置
{"^u-(.*)": "components/u-$1.vue"}—— 这样写<u-button></u-button>就能自动找components/u-button.vue - 排除测试组件：用负向断言
{"^(?!test-).*": "components/$1.vue"}，但注意 Webpack 5+ 对负向断言支持有限，更稳妥的是直接用白名单方式，比如{"^u-(.*)": "components/u-$1.vue", "^uni-(.*)": "components/uni-$1.vue"} - 路径中含多级目录时，
$1只捕获括号内容，不会带斜杠；若要支持components/form/Select.vue被<form-select>匹配，得写成{"^form-(.*)": "components/form/$1.vue"}
easycom 在不同平台的行为差异
easycom 在微信小程序、App、H5 表现不一致——不是 bug，是底层构建机制不同导致的加载时机和作用域差异。
实操建议：
- 微信小程序：easycom 是编译时处理，组件必须在
components下且命名合法，否则构建时报错（如Invalid component name） - H5：依赖 Vue 3 的异步组件 + webpack resolve.alias，若你用的是
vue.config.js自定义配置，记得调用config.resolve.alias.set并确保chainWebpack中启用了compilerOptions.easycom - App（nvue）：不支持 easycom，必须手动
import+components注册，否则直接白屏或报Component is not found
组件名冲突时 easycom 怎么优先级判断
当页面里既有 <my-button>，又有同名的本地 import MyButton from './MyButton.vue'，或者多个 components 子目录下存在同名文件，easycom 的加载顺序会影响最终结果。
实操建议：
- easycom 的匹配是“先到先得”：配置数组越靠前，优先级越高；多个正则都匹配时，取第一个成功的结果
- 避免跨目录重名：比如
components/base/Button.vue和components/form/Button.vue都想响应<button>，那必须用不同前缀（如base-button/form-button），否则后者会覆盖前者 - 局部注册仍高于 easycom：如果在页面中写了
components: { 'my-button': MyButton }，那即使components/my-button.vue存在，也不会被 easycom 拦截
真正容易被忽略的是：easycom 的路径解析发生在编译阶段，不感知运行时条件；所以动态组件名（如 <component :is="name">）永远不会触发 easycom，得自己 resolve。
