UniApp z-paging easycom 与 vite-plugin-uni-components 冲突导致 CICD 构建产物组件渲染异常

在 UniApp 项目中同时使用 z-paging 的 easycom 配置和 @uni-helper/vite-plugin-uni-components 时，本地开发一切正常，但一旦走 CI/CD 流程打包到 H5，使用了 z-paging 的组件会直接渲染出 <z-paging> 原始标签，自动导入完全失效。

问题现象

在 CI/CD 环境执行 H5 打包后，页面上原本应该渲染为分页列表的区域，变成了浏览器无法识别的 <z-paging> 自定义标签，内容完全不显示。

本地开发环境（pnpm dev）和本地手动打包（pnpm build）均正常，仅在 CI/CD 流水线中打包的产物出现此问题。

根本原因

z-paging 官方文档推荐通过 pages.json 的 easycom 字段进行注册：

// pages.json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^z-paging": "@/uni_modules/z-paging/components/z-paging/z-paging.vue"
    }
  }
}

而项目同时使用了 @uni-helper/vite-plugin-uni-components 来实现 Vite 层面的自动组件导入。

两套机制在本地可以共存，因为本地环境有一定的容错处理。但在 CI/CD 的干净构建环境中，两者发生冲突：easycom 的配置干扰了 vite-plugin-uni-components 的解析，导致插件无法正确识别和导入 z-paging 组件，最终输出的 HTML 里保留了未解析的原始标签。

复现条件

• 使用 UniApp + Vite 构建 H5
• pages.json 中配置了 z-paging 的 easycom 规则
• 同时安装并启用了 @uni-helper/vite-plugin-uni-components
• 在 CI/CD 流水线（如 GitHub Actions、Jenkins 等）中执行打包

解决方案

两步操作，缺一不可：

第一步：删除 easycom 中的 z-paging 配置

移除 pages.json 中 z-paging 的 easycom 注册规则，让组件完全交由 vite-plugin-uni-components 管理：

// pages.json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      // ❌ 删除这一行
      // "^z-paging": "@/uni_modules/z-paging/components/z-paging/z-paging.vue"
    }
  }
}

第二步：更新 @uni-helper/vite-plugin-uni-components

将 @uni-helper/vite-plugin-uni-components 升级到 0.3.2 及以上版本，旧版本在处理 uni_modules 目录下的组件时存在解析缺陷：

pnpm add @uni-helper/vite-plugin-uni-components@^0.3.2

确认 vite.config.ts 中插件已正确配置（通常保持默认即可）：

// vite.config.ts
import UniComponents from '@uni-helper/vite-plugin-uni-components'

export default defineConfig({
  plugins: [
    UniComponents({
      // 默认会自动扫描 src/components 和 uni_modules 目录
    }),
  ],
})

验证

修改完成后，在 CI/CD 中重新触发打包，检查产物是否正确渲染 z-paging 组件。

也可以在本地模拟 CI 环境（清除缓存后重新安装依赖并打包）来提前验证：

# 清除依赖缓存，模拟 CI 环境
rm -rf node_modules
pnpm install --frozen-lockfile
pnpm build:h5

测试环境

以下为问题复现及修复验证时使用的依赖版本：

总结

这个问题的隐蔽性在于本地和 CI/CD 环境行为不一致，排查时容易忽略构建环境差异。当你遇到"本地正常但打包后组件不渲染"的情况，首先检查是否存在多套组件注册机制并行的情况。