easycom配置必须位于pages.json根对象顶层，与pages、globalStyle同级；autoscan设为true才扫描components目录，custom规则需用合法正则和路径模板，组件须存于标准components目录且命名规范，修改后需重启编译生效。
easycom 配置必须写在 pages.json 的顶层，不能嵌套
很多人把 easycom 写在 globalStyle 或 tabBar 里，结果完全不生效。它和 pages、subNVue 是同级字段，必须直接放在 pages.json 根对象下。
常见错误写法：
{
"globalStyle": { ... },
"easycom": { ... } // ❌ 错！被当成 globalStyle 的子属性
}
正确结构示例：
{
"pages": [...],
"subNVue": [...],
"easycom": { // ✅ 对！和 pages 并列
"autoscan": true,
"custom": {
"^uni-": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue"
}
},
"globalStyle": { ... }
}
-
autoscan设为true才会扫描components/目录下的组件（默认就是true，但显式写出更稳妥） -
custom是可选的，但只要写就要是合法 JSON 对象，空对象{}也比留空或写成null安全 - H5 端需额外确认：若使用
vue.config.js，里面不能覆盖或禁用compilerOptions.easycom，否则pages.json的配置会被忽略
正则匹配规则写错会导致组件找不到
匹配规则的 key 是正则字符串，value 是路径模板，$1 表示第一个捕获组内容。写错括号、漏转义、路径斜杠方向不对，都会让 <u-button></u-button> 这类标签无法解析。
典型问题：
- 想匹配
components/form/Select.vue，却写成"^form-(.*)": "components/form/$1.vue"→ 实际会去找components/form/Select.vue，但组件名是form-select，$1捕获的是select，没问题；但如果组件叫form-date-picker，$1就是date-picker，路径就得是components/form/$1.vue，而实际文件可能是components/form/date-picker.vue—— 这时就得改规则为"^form-(.*)": "components/form/$1/$1.vue"或拆成多条规则 - 路径中用了相对路径如
../components/xxx.vue→ uni-app 不支持向上跨目录，只认项目根目录起始的路径（@/或components/） - value 中写了
.jsx或.ts后缀 → easycom 只识别.vue和.tsx（且需对应编译支持），其他后缀无效
components 目录位置和命名不合规，easycom 直接跳过
easycom 不会扫描任意位置的组件目录，只认项目根目录下的 components/（与 pages/ 同级），且有硬性限制：
Comprehensive Three.js 3D graphics reference
下载
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
- 目录名必须是
components，不能是comp、my-components或带前缀如__components - 子目录不能以
__或.开头（例如components/__base/或components/.utils/会被跳过） - 组件文件名必须是 PascalCase（如
MyButton.vue），且组件内部export default { name: 'MyButton' }必须一致；否则 H5 端 fallback 注册可能失败 - 文件扩展名只能是
.vue或.tsx；.js或.json文件不会被识别为组件
如果组件放到了 src/components/ 下，easycom 默认不会扫 —— 此时要么移动目录，要么在 custom 规则里用别名映射，比如 "^u-(.*)": "src/components/u-$1.vue"。
修改 pages.json 后组件没更新，不是配置问题而是缓存没清
uni-app 编译器对 pages.json 的改动不敏感，改完 easycom 后常出现“明明配了却还是 Unknown custom element” —— 很大概率是缓存没刷新。
- 重启 HBuilderX 或命令行
npm run dev:mp-weixin等启动命令（不是热更新，是彻底重启） - 删掉
unpackage/目录再重新编译 - 检查控制台是否有类似
Component not found: u-button的警告，它会提示具体缺失的路径，比报错更有用 - 小程序开发者工具里勾选「关闭 ES6 转 ES5」有时会影响 easycom 解析（尤其含
import.meta的场景），建议保持默认开启
真正容易被忽略的点是：easycom 是按需局部引入，不是全局注册。哪怕配置全对，<u-button></u-button> 在某个页面里第一次出现时才加载，所以得真正在模板里写一次、保存、预览，才能验证是否生效。
