以前写 uni-app，每要用一个组件，就得在页面的 import 和 components 里写两遍，稍微多几个组件，文件头部又臭又长。后来朋友告诉我有个叫 easycom 的东西，用起来真心舒服。但用着用着，发现也不是所有时候都听话，今天把我自己的配置过程和一些坑记录下来。
一、easycom 是啥？
说人话：开启 easycom 之后，你在 pages.json 的模板里直接写某个组件标签，uni-app 会自动帮你找到并加载这个组件，不需要手动 import，也不需要反向注册。只要组件的目录结构和命名符合规则，它就能被自动扫描到。
二、最简单的默认规则
新建一个 uni-app 项目，默认就开了 easycom 的扫描。它的规则就是把 components/组件名/组件名.vue 直接映射成页面里的 <组件名 />。
举个例子，我项目下有一个 components/avatar-card/avatar-card.vue，那么任何页面我都可以直接写：
<avatar-card :user="userInfo" />完全不用在 script 里写 import。就这一条，节省了不少无意义的代码。
三、完整做一个小demo
照着这个思路，我写了一个简单的 auth-btn 组件，用来展示当前的登录状态，一个按钮，没点击时就弹个提示。
文件结构：
src/
├── components/
│ └── auth-btn/
│ ├── auth-btn.vue
│ └── auth-btn.js // 如果单独抽逻辑可以放这
└── pages/
└── index/
└── index.vueauth-btn.vue 里的代码长这样：
<template>
<view class="auth-btn-wrap">
<button :class="isLoggedIn ? 'logged' : ''" @click="handleClick">
{{ isLoggedIn ? '已登录' : '去登录' }}
</button>
</view>
</template>
<script>
export default {
data() {
return {
isLoggedIn: false
};
},
methods: {
handleClick() {
if (!this.isLoggedIn) {
uni.showToast({ title: '需要先登录哦', icon: 'none' });
return;
}
uni.showToast({ title: '欢迎回来', icon: 'success' });
}
}
};
</script>然后在 pages/index/index.vue 里，直接写 <auth-btn />，就完事了。
<template>
<view>
<auth-btn />
</view>
</template>
<script>
// 这里不需要 import auth-btn
export default {
data() {
return {};
}
};
</script>我用 HBuilderX 的模拟器跑了一下，组件正常渲染。那一刻确实舒服，但也就高兴了半小时。
四、遇到第一个坑：自定义目录就失效了
然后项目大了，我想把业务组件放到 src/components/business/ 下面去，于是写成 src/components/business/order-card/order-card.vue。结果页面里用 <order-card /> 直接报错——找不到组件。因为 easycom 默认只扫描 components/组件名/组件名.vue 这种两层结构。
这时候需要自己在 pages.json 里配置 easycom.custom，让它可以自动匹配到多层目录。
"easycom": {
"autoscan": true,
"custom": {
"^order-(.*)": "@/components/business/order-$1/order-$1.vue"
}
}这里我用了一个正则，把 order-card 匹配成 order-card/order-card.vue。写完记得重新运行，配置才会生效。
五、第二个坑：node_modules 里的组件不能被自动扫描？
后来我装了第三方组件库，比如 uni-ui，用 npm 方式安装的。这时候 easycom 也能识别，但需要自定义规则，尤其那些带 scope 包名的组件。官方文档也有，但一开始我直接看蒙了。
比如安装了一个包叫 @x-components/rate，它的组件名是 XRate，但实际标签写 <x-rate>。要在 easycom 里这么配：
"easycom": {
"custom": {
"^x-(.*)": "@x-components/x-$1/x-$1.vue"
}
}如果 npm 包装到 node_modules 里，实际路径可能需要这样写：
"^x-(.*)": "@x-components/component-vue/x-$1.vue"得根据包的实际目录来，不能凭感觉。后来我干脆去看那个 npm 包的 package.json 里的目录结构，才把路径写对。
六、最容易踩的坑：组件的 name 和路径不一致
有次我从老项目复制了一个 user-list.vue，但里面 name: 'userList'。我在新页面里写 <user-list>，结果它没识别成同一个组件。为什么？因为 easycom 是“按路径猜组件名”，它用标签名去匹配路径。如果你路径叫 user-list，标签也写 user-list，那就没问题。但组件内部 name 叫 userList，虽然不影响 easycom 的引入，但如果你同时在同一个页面显式 import 了一个相同 name 的组件，可能有冲突。更常见的是，路径使用驼峰（userList.vue）标签却写成了短横线（<user-list>），就容易找不到。
所以约定就是：路径中的文件名、目录名、标签名尽量保持一致，要么全用短横线，要么全用驼峰。我最后统一改了文件夹名字为 user-list，不再折腾。
七、显式 import 与 easycom 同时存在时，谁赢？
有一次我想覆盖某个 easycom 组件的部分逻辑，于是在页面里手动 import 了一个同名组件，想着“优先用我的”。结果发现根本不起作用，页面还是用了 easycom 匹配到的那个。查了一下才知道：easycom 的优先级其实比自己 import 低？但实际上它还是先去找 easycom 的规则，匹配到了就用那个，如果找不到才用 import 的。
手动 import 之前，必须让 easycom 不要匹配到相同标签。最干净的办法是，在自定义规则里把那个组件排除掉，或者干脆在路径上改个名字。
八、性能方面的注意
自动扫描确实省心，但不是没有代价。项目里组件特别多的时候，每次编译都要去遍历 components 目录，寻找匹配项，开发环境下稍慢一点。我自己试过把一个目录层级做得特别深，结果第一次编译肉眼可见卡了一下。
所以我的建议是：如果项目已经稳定了，把 autoscan 设为 false，只开 custom 规则，让 easycom 按你给的正则去找，不再全盘扫描。
"easycom": {
"autoscan": false,
"custom": {
"^my-(.*)": "@/custom-components/my-$1/my-$1.vue"
}
}这样更可控，也不会每次构建都去检查一大堆无关文件夹。
九、总结一下我现在的优雅配置
说夸张一点，我现在已经离不开 easycom 了。但用多了之后，也总结了自己一套配置习惯：
- 组件目录统一放在
src/components下，不要乱扔。 - 所有业务组件都以 “a-” 开头，方便用正则匹配，比如
a-input-wrapper。 - 关闭 autoscan，使用精确的自定义规则，避免莫名其妙匹配到第三方包里的组件。
- 遇到特别通用的组件，还是老老实实写在
components/组件名/组件名.vue里，享受默认规则。
下面是我当前使用的 pages.json 片段，可以给你参考：
{
"easycom": {
"autoscan": false,
"custom": {
"^a-(.*)": "@/components/a-$1/a-$1.vue",
"^uni-(.*)": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue"
}
}
}第一行匹配自己的业务组件，第二行匹配 uni-ui。以前那些又臭又长的 import 和 components 声明全没了，页面清爽到不像话。
十、最后一个建议
如果你刚接触 easycom，别一股脑全盘自动扫描。先建一两个组件，试试默认规则，然后马上遇到自定义需求，再去看自定义规则。踩坑是最好的学习方式，我就是这么过来的。现在我的项目里有40多个业务组件，但 pages.json 里关于 easycom 的配置就那么几行，所有页面都是直接写标签，没有多余 import。
这大概就是前端工程化的小快乐吧。
