企业官网建设流程全解析

1. page.json 还是 pages.json：easycom 配置位置的辨析

在跨端开发里，这个问题踩坑率极高：想给某个页面引入一个自定义组件，于是打开页面目录下的page.json，写上一段easycom配置，保存、重新编译，结果组件依旧是"未注册组件"的报错。原因其实很朴素——放错文件了。

easycom不是微信小程序原生规范里的东西，它是一层编译期的组件自动引入机制，归属于跨端框架的构建体系，配置文件是项目根目录的pages.json，写在它的根节点下。而page.json是微信小程序原生的页面级配置文件，由小程序基础库读取，只认官方定义的那几个字段。你在page.json里写easycom，小程序基础库不认识，构建工具也不会把它当成全局规则去解析，等于写了一段装饰性文本。

这个辨析是整篇文章的地基。地基错了，后面所有排查都是在错误的方向上使劲。

1.1 原生小程序的 page.json 到底能写什么

原生小程序的页面配置是"就近覆盖"逻辑：全局app.json里配window，页面目录下的page.json用来覆盖当前页面的窗口表现和组件声明。它支持的字段就那么一批，常用的有：navigationBarTitleText、navigationBarBackgroundColor、navigationBarTextStyle、backgroundColor、enablePullDownRefresh、onReachBottomDistance、disableScroll、usingComponents，以及一些扩展能力相关的开关。

其中和本篇关系最直接的是usingComponents。它是一张映射表，键是你在模板里使用的组件名，值是组件文件路径。路径有两种写法：

{ "usingComponents": { "my-card": "/components/my-card/my-card", "my-tag": "../../components/my-tag/index" } }

以/开头的是项目根目录绝对路径（注意不是文件系统绝对路径），不带/的是相对当前页面 json 所在目录的路径。两种混用是常见事故源：页面层级一动，相对路径就断了；改成绝对路径，又要保证目录结构稳定。手动维护这张表的痛苦，正是easycom这类机制被造出来的原因——尤其在组件数量破百之后，每加一个组件，你都得回到页面配置里补一行。

提示：usingComponents的值不要带.js、.vue后缀。小程序运行时会按约定去补全文件名，你多写一个后缀反而找不到组件。

另外要清楚一点：page.json只在原生小程序项目里生效。在跨端框架的项目源码里，页面级配置一般写在pages.json的pages数组里每个页面的style字段中，由构建工具在编译时生成各页面的page.json。所以你在源码目录下手动新建一个page.json，大概率会被编译流程无视，或者直接覆盖丢失。

1.2 easycom 为什么只能落在 pages.json 根节点

easycom干的活是编译期静态分析：扫描你的模板里出现了哪些组件标签，反查规则表，找到对应的组件文件路径，最后把这些路径塞进当前页面的usingComponents里。这个动作必须发生在"模板解析完成之后、页面配置产出之前"，而掌握这两个时机的只有构建工具本身。

把它放在pages.json根节点，语义是"全局生效，所有页面共用一套规则"。这也符合它的工作方式——规则表是编译期的全局状态，不是某个页面的私有属性。你想想，如果允许每个页面写一套easycom规则，编译器就得为每个页面维护独立的规则上下文，规则冲突、优先级判定都会变得不可控，收益却几乎为零。

配置的骨架长这样：

{ "easycom": { "autoscan": true, "custom": { "^my-(.*)": "@/components/my-$1/my-$1.vue" } }, "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } } ] }

autoscan控制默认扫描规则是否启用，custom是你自定义的正则映射表。注意@/这个前缀，它指向项目根目录，是构建工具的路径别名，不是小程序原生认识的东西——构建时会被替换成真实路径。

还有一条容易忽略的：easycom是根级字段，不能塞进pages数组里某个页面的style中。写错位置不会报错，只是安静地不生效，排查起来极其折磨人。

2. easycom 的匹配引擎：目录名、正则与优先级

搞清位置之后，真正决定成败的是匹配规则。很多人以为easycom是"目录里放了组件就能用"，实际上它有两套并行的匹配逻辑：一套是内置的默认扫描规则，一套是你手写的custom正则。两者触发条件、命名约束完全不同，混着理解必然出问题。

我见过最典型的现象：同事把一个叫user-avatar的组件放进了components目录，目录结构是components/avatar/user-avatar.vue，然后抱怨easycom不生效。问题就在这儿——默认规则要求目录名和文件名一致，avatar目录下必须叫avatar.vue，否则匹配不上。

2.1 默认扫描规则的三个硬性条件

autoscan为true时（默认值），编译器会去扫描项目根目录下的components文件夹，按固定套路匹配。这个套路有三个条件，缺一不可：

• 组件必须位于根目录components下，且是"目录 + 同名文件"结构，即components/xxx/xxx.vue；
• 模板里使用的标签名必须能与目录名对应，components/user-card/user-card.vue对应模板中的<user-card />；
• 组件文件必须以.vue结尾（这是跨端框架的约定，easycom只处理单文件组件）。

符合这三条，你在任何页面里直接写<user-card />，不用import、不用components注册、不用改page.json，编译后自动进入该页面的usingComponents。

这套规则的巧妙之处在于"零配置"。团队约定好组件目录规范之后，新人加组件不需要碰任何配置文件，减少了一整类合并冲突。代价是目录结构被锁死——你不能既有components/user-card/index.vue又有components/user-card/user-card.vue混着来，前者默认规则压根扫不到。

我自己的目录习惯是：所有走easycom的通用组件，一律components/组件名/组件名.vue；需要额外资源（图片、样式文件、工具函数）的组件，把资源放在同一目录下，文件名仍然与目录同名。这样目录一眼能看出是不是easycom组件，不需要去翻配置。

2.2 custom 正则的写法与转义陷阱

自定义规则的值是一张映射表，键是正则字符串，值是可以带捕获组替换的组件路径。几个硬性约束必须记住：

举个实际在用的例子。组件库的命名习惯是xxx-button、xxx-dialog，全部平铺在一个包里：

{ "easycom": { "autoscan": true, "custom": { "^ui-(.*)": "@/components/ui-kit/ui-$1.vue", "^chart-(.*)": "@/components/charts/$1/index.vue" } } }

模板里写<ui-button />，编译器拿标签名去匹配^ui-(.*)$，捕获到button，拼出@/components/ui-kit/ui-button.vue。写<chart-line />，捕获line，拼出@/components/charts/line/index.vue。

转义这块单独提一句。假设你的规则里需要用\d匹配数字：

{ "^icon-(\\d+)$": "@/components/icons/icon-$1.vue" }

JSON 解析会先吃掉一层反斜杠，最终传给正则引擎的才是\d。只写一个\会导致 JSON 解析阶段就报非法转义字符，或者被静默吞掉变成d，正则语义完全变了。这个坑我在两个项目里各踩过一次，第二次是因为复制了别人配置文件里的单反斜杠写法。

2.3 优先级与组件名冲突的判定顺序

当同一个标签名同时被多套规则命中，谁说了算？判定顺序是：custom中靠前的规则优先，其次才轮到autoscan的默认规则。这条优先级设计得很实用——你想改造某个默认组件的来源，不用改目录结构，加一条更靠前的custom规则就能截胡。

举个真实场景：项目里原本有个components/button/button.vue，后来设计规范升级，统一换成组件库的实现。最省事的做法不是删掉旧组件（页面还在引用），而是加一条规则把它指向新实现：

{ "easycom": { "autoscan": true, "custom": { "^button$": "@/components/ui-kit/button-v2.vue" } } }

这里^button$精确匹配，只截button这一个标签，不影响button-group。如果你写成^button，那button-group也会被它截走，拼出不存在的路径，报错信息还指向一个你没有直接引用的文件，非常迷惑。

提示：改造默认组件时，一定用$收尾做精确匹配。前缀匹配是"组件名互相污染"的头号原因。

3. 接入组件库：从内置规则到 npm 包的完整链路

easycom最省事的地方在于组件库的接入。不少组件库本身就提供了easycom规则片段，你只要把那段 JSON 复制到pages.json根节点即可，不需要逐页注册、也不需要Vue.use()之类的手动安装。但"复制粘贴就能跑"的背后有几个细节，出问题时往往就卡在这些细节上。

3.1 组件库自带规则的接入姿势

典型的组件库规则形态是：包安装在node_modules下的某个子目录，内部按组件名分目录，每个目录下有一个同名的.vue文件。规则长这样：

{ "easycom": { "autoscan": true, "custom": { "^uni-(.*)": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue" } } }

接入顺序建议按这个流程走：

1. 先确认依赖已经装进node_modules，且版本与当前框架版本兼容（版本不匹配时，组件能编译但运行时行为异常，比直接报错还难查）；
2. 把官方规则片段粘进pages.json的根级easycom.custom，注意别粘到别的字段里；
3. 首次使用需要完全重新编译，热更新有时不会重新触发easycom的规则扫描；
4. 在页面模板里写一个最简单的组件，比如按钮，编译后打开微信开发者工具，看该页面的 json 里是否出现了usingComponents条目。

第 4 步是必须做的验证动作。我见过好几次"组件库装了、规则配了、页面里就是没反应"，最后发现是组件库压根没被编译进产物——node_modules里的包如果没被维护者标记为需要编译，构建工具会直接跳过它，产物里根本没有对应的组件文件，usingComponents指向一个空路径，小程序端就会报组件找不到。

3.2 给第三方 npm 组件手写规则

不是所有组件库都提供现成的easycom规则。尤其是一些你自己封装的内部包，或者从别的项目搬过来的组件，目录结构往往是lib/组件名/index.vue这种形态。这时候你需要手写一条规则。

假设内部包叫@team/widgets，目录结构是node_modules/@team/widgets/lib/button/index.vue：

{ "easycom": { "custom": { "^tw-(.*)": "@team/widgets/lib/$1/index.vue" } } }

模板里写<tw-button />，捕获button，拼成@team/widgets/lib/button/index.vue。

手写规则有三个经验点：第一，先在文件管理器里把真实路径走一遍，确认大小写和层级完全一致，Linux 环境和 Windows 环境对文件名大小写敏感度不同，本地能跑、流水线构建失败的事故大多源于此；第二，组件包如果带样式依赖（比如需要引入一个基础样式文件），easycom只管组件引入，不管样式引入，基础样式还得在入口文件里手动import；第三，路径里的@开头是别名，指向项目根目录，别和你自己的 npm scope（同样以@开头）搞混，@/xxx和@team/xxx是两回事。

3.3 某个页面想绕开 easycom，手动声明组件

easycom是全局规则，但总有特殊情况需要单页覆盖。比如某个页面要临时用一个实验性组件，不想把它纳入全局命名空间；或者某个页面的组件必须带特定的小程序扩展配置（如styleIsolation、componentPlaceholder）。

这时可以在pages.json里对应页面的style.usingComponents中显式声明：

{ "pages": [ { "path": "pages/detail/detail", "style": { "usingComponents": { "exp-panel": "/components/experimental/panel" } } } ] }

需要注意，页面级显式声明与easycom的优先级关系是：显式声明优先。同名的标签，页面里写了usingComponents，就走你写的路径，easycom的规则不再介入。这个特性可以用来做灰度——同一个组件名，在灰度页面指向新实现，其他页面保持旧实现。

注意：显式声明里写的路径是给小程序运行时看的，要按小程序的路径规范写（/开头或相对路径），不能写@/别名。别名只在源码和easycom规则里有效，写进usingComponents会导致编译产物里出现无法解析的路径。

4. 编译产物验证：easycom 最终变成了什么

排查easycom问题，最高效的方式不是猜，而是看产物。跨端框架最终交付给小程序的是一个标准的小程序工程，所有easycom的魔法都必须在那个工程里现出原形。看懂产物，等于拿到了唯一的真相来源。

4.1 在产物目录里核对页面 json

编译后的产物通常在项目的dist/dev/mp-weixin（开发模式）或dist/build/mp-weixin（生产模式）目录下（具体目录名取决于你的构建设置）。打开pages/detail/detail.json，你应该能看到类似结构：

{ "usingComponents": { "ui-button": "../../components/ui-kit/ui-button", "user-card": "../../components/user-card/user-card" }, "navigationBarTitleText": "详情" }

这里有两件事值得核对。第一，标签名的大小写。源码里写<UiButton />或<ui-button />，产物里通常会被统一成 kebab-case（短横线形式），这是小程序自定义组件命名规范的约束，小程序端不认驼峰式组件名。如果你在模板里用了驼峰并且发现不生效，先怀疑这里。

第二，路径的解析结果。easycom规则里的@/会被替换成相对路径或绝对路径，如果规则写错，产物里的路径会指向一个不存在的文件，编译工具不一定报错，但小程序端会在控制台抛出组件查找失败的提示。看到这类报错，直接拿产物里的路径去文件树里对一遍，问题位置立刻现形。

还有一个动作值得养成习惯：在微信开发者工具里看页面的WXML面板，组件标签如果被渲染成一个自定义组件节点，说明注册成功；如果渲染成一段文本或者干脆消失，说明没注册上。这比看控制台报错更直观。

4.2 分包场景下组件会被打进哪个包

分包是easycom里最容易被忽略的一角。组件被编译进哪个包，取决于引用它的页面在哪个包，但这里的机制比想象中微妙。

主包页面引用的组件，必然打进主包。分包页面引用的组件，构建工具有时会尝试把它放在分包内，以减少主包体积。但跨分包引用会出问题：A 分包页面引用了easycom组件，B 分包页面也引用同一个组件，构建工具只能把它放在一个地方，另一个分包就得跨包引用。跨包引用的限制是硬性的——小程序的组件不能跨分包直接引用主包之外的其他分包资源。

我的处理策略是：高频通用组件放主包components目录，走默认easycom规则；低频、只在单个分包内使用的组件，放在分包自己的目录下，用custom规则显式指过去。比如：

{ "easycom": { "autoscan": true, "custom": { "^pkg-order-(.*)": "@/pages/order/components/$1/index.vue" } } }

这样订单分包专属的组件不会污染主包，主包体积能压下来几十到上百 KB。主包体积对小程序的首屏加载时间影响非常直接，有些平台的包体积限制还卡得很死，这一块值得认真规划。

代价是规则表会变长，可读性下降。我在项目里会给custom规则加注释——虽然 JSON 不支持注释，但会把规则按业务域分组，组与组之间用命名前缀区分（pkg-order-、pkg-pay-、ui-），一眼能看出归属。

5. 不生效排查：高频链路逐条走

easycom的报错信息普遍不太友好，经常只是一句"组件未找到"或者干脆静默失败。下面这套排查链路是我在多个项目里反复验证过的，按顺序走，基本能定位到根因。

5.1 第一环：命名与路径是否严格对齐

先做最机械的核对。默认规则下，问三个问题：目录名和文件名是不是完全一致？目录是不是在项目根目录的components下？文件扩展名是不是.vue？三问有一个否，就不走默认规则。

custom规则下，做四件事：把正则单独拿出来，用标签名跑一遍，看是否命中；确认捕获组的编号和值里的$1对得上；确认值以.vue结尾；确认路径真实存在。这四步里第三、四步最容易漏，而它们的报错信息最不直观。

还有一种隐蔽情况：组件名与某个原生组件或框架内置组件重名。比如你把组件命名为view或text，产物里会和原生标签打架，表现是渲染异常而不是报错。避免这类问题的做法很简单，给自定义组件统一加业务前缀，全局搜索一下名字有没有撞车。

5.2 第二环：改动是否真正生效

easycom的规则表是编译期读取的，修改pages.json之后，热更新不保证会重新触发规则扫描。这是我在实际项目里被折腾最多的一环：明明改了配置，页面就是不变，重启一次全好了。

规避方式：

• 改pages.json的easycom部分后，手动停止编译再重新启动；
• 微信开发者工具侧同时做一次"清缓存 → 全部清除"，避免它拿着旧的组件注册表；
• 产物目录（dist）可以整体删掉重编，比等它自己增量更新更可靠。

如果项目配了环境变量或多环境配置文件，还要确认改动的是当前编译环境读取的那份配置。曾经有个项目把pages.json拆成了多份按环境合并的配置，同事改的是开发环境那份，但他跑的是另一个环境的编译命令，白折腾了一个下午。

5.3 第三环：组件内部依赖与平台差异

组件被正确注册了，但页面白屏或者报错，问题在组件内部。常见有三类。

第一类是组件自身没做平台兼容。easycom只是引入机制，它不会帮你适配平台。组件里用了浏览器专有 API（window、document、localStorage），在小程序端直接崩。这类问题在跨端组件库里偶有发生，用之前先看组件文档的平台支持说明。

第二类是样式隔离。小程序的自定义组件默认样式隔离，父页面里写的选择器打不进组件内部。表现是"组件渲染出来了，但是样式全乱"。解决办法是在组件里显式配置options: { styleIsolation: 'shared' }，或者干脆用组件内部的类名体系写样式，别指望从外面覆盖。

第三类是组件依赖的插件或分包资源没就位。有些组件内部引用了其他组件或工具模块，easycom只解析顶层那一个，内部的依赖要靠组件自己的导入语句。如果内部依赖也是通过easycom自动引入的，那规则必须同样覆盖到，否则编译能过，运行时报错。

5.4 第四环：条件编译带来的规则差异

跨端项目常用条件编译做平台差异。如果easycom规则里也用了条件编译（某些框架支持在配置里写条件编译注释），要确认当前编译目标平台对应的那段规则确实存在。

更常见的是组件文件本身带了条件编译块。同一份.vue在 A 平台编译出来是完整组件，在 B 平台可能只剩下一个空壳，表现就是"组件注册了但什么都不显示"。排查方法是在产物目录里打开对应平台的组件文件，看内容是否完整。

6. 工程化取舍：easycom 用多深才合适

easycom用起来爽，但它不是银弹。用得深了会带来两个副作用：组件来源的"可见性"下降（新人看模板里的标签，不知道它到底来自哪个文件），以及组件数量暴涨后的编译耗时上升。什么程度算合适，取决于团队规模和组件的复用频率。

6.1 与手动引入的对比

把两种方式摆在一起看，取舍会清晰很多。

我的实际做法是分层：基础层（按钮、卡片、弹窗、表单控件）全部走easycom，命名统一前缀；业务层组件如果只在两三个页面用，就走页面级显式声明，不往全局规则里塞。这样既能享受自动引入的便利，又不至于让全局命名空间膨胀到无法管理。

一个具体的数字感受：一个中等规模的小程序项目，components目录下走了easycom的组件大约三四十个，业务组件上百个但都按页面就近放、显式引入。这个比例下编译耗时可控，同时模板里看到的标签基本能在规则表里一眼查到。

6.2 组件目录与规则表的组织建议

组件目录结构一旦定下来，中途改动成本很高，值得一开始就想清楚。我目前的组织方式是三层：

• components/base/下的基础组件，走默认规则不合适（默认规则不认二级目录），所以用一条custom规则统一映射："^b-(.*)": "@/components/base/$1/$1.vue"；
• components/biz/下的跨业务组件，同样走custom规则，前缀bz-；
• 分包专属组件放在各分包目录内，规则前缀带上业务标识，如pkg-order-。

规则表本身也有维护技巧。它是 JSON，没法写注释，所以我把规则按前缀分组排列，组内按字母序，组间空行分隔（虽然空行会被格式化工具吃掉，但排列顺序本身传递了分组信息）。另外在项目文档里维护一张"前缀 → 目录"的对照表，新人接手时不需要逆向规则表。

还有一个我踩过的坑值得提醒：不要在easycom规则里写会命中大量标签的宽泛正则。比如"^(.*)$": "@/components/$1/$1.vue"这种写法，看着万能，实际上会让编译器对每一个无法识别的标签都去尝试匹配，编译时间肉眼可见地变长，而且一旦某个标签拼错，报错会指向一个完全不相关的组件路径，排查成本翻倍。规则的口子开多大，取决于你能承受多少误命中。

最后提一个实际的收益点：easycom因为"用到才引入"的特性，天然具备按需打包的效果。项目里有二十多个组件，实际被模板引用的可能只有一半，未被引用的不会进入产物。这一点比全量注册组件库省下的体积，在包体积吃紧的项目里往往能救急。我做过一次对比，同一个项目，把组件库全量import改成easycom按需引入，主包体积少了将近一百 KB——这个数字在小程序里不算小。

用不用、用多深，最终还是要回到你的项目形态上：组件库主导、页面形态统一的，放心用；业务复杂、组件生命周期短、多人并行开发的，建好目录规范再上，别边写边定规矩。