组件升级没有改动多少业务代码，却可能让打包流程变得难以复现。这里不讨论依赖版本漂移，也不把三方包质量一概归咎于包管理器。本文处理一个更小的切口：第三方 ArkUI 组件的源码资源目录中，大小写不同的文件名被当作不同资源，或者资源引用的字母大小写与实体文件不一致。在某些开发机文件系统上，团队可能不容易察觉差异；换到另一类大小写规则的环境，预检、复制、版本控制与构建链条便可能给出不同结果。这是一份可以放在工程构建前的 Node.js 静态检查方案。演示项目叫 CaseGate，批次 CG-083。准备一个模拟的 vendor-ui/resources/base/media 目录，里面一共 28 个文件：其中 Badge.svg 与 badge.svg 构成 1 组名称大小写碰撞；演示引用清单写的是 userIcon.svg，实际文件为 UserIcon.svg，形成 1 处引用错配。最终门禁状态为 BLOCKED。这些数字由构造数据定义，并非 HarmonyOS 真机日志或某个真实第三方厂商的缺陷统计。## 一、先把“文件能看到”和“构建能找到”拆开三方 UI 组件中常见两层资源：其一是源目录里的图标、插画、字体等文件，其二是 ArkUI 页面通过资源标识或组件内部路径使用它们的方式。把二者写成一个问题，容易导致扫描器报得过宽。本文只检查你确实能够获取并纳入源码管理的资源快照，不读取未知 HAR 的内部私有结构，也不把 $r('app.media.xxx') 与文件名直接当成同一套解析规则。在演示目录里，Badge.svg 和 badge.svg 在某些环境下可以共存，但跨系统复制、解压或某些打包步骤可能产生覆盖或冲突。反过来，userIcon.svg 在文本里出现，并不等于 UserIcon.svg 就是它的正确指向。文件系统是否区分大小写、资源编译器如何映射标识、最终产物有没有真正引用对应文件，是三个需要分别验证的环节。所以第一条工程约束不是“扫描出同名就删除一张”，而是先固定检查范围：版本化的 vendor-ui 源码快照，以及项目明确维护的引用清单。资源真正进入 entry/src/main/resources 的路径还需要以目标工程的配置为准。这一步不以 ohpm list 的依赖树替代物理文件核查；后者只能帮助知道依赖是谁，不能证明每个资源文件的拼写都正确。## 二、把目录枚举留在脚本里，而不是猜测资源 API问题： 首先拿到稳定、可审阅的文件名集合，不能让操作系统目录遍历顺序影响报告。下面使用 Node.js 内置 fs 和 path，不依赖 HarmonyOS 的未验证接口，也不强行扫描 .har 压缩产物。javascriptimport { readdirSync } from 'node:fs';import { resolve } from 'node:path';function listMediaNames(dir) { return readdirSync(dir, { withFileTypes: true }) .filter((item) => item.isFile()) .map((item) => item.name) .sort((a, b) => a.localeCompare(b, 'en'));}const mediaDir = resolve('fixtures/vendor-ui/resources/base/media');const files = listMediaNames(mediaDir);上面枚举的是单层目录，适合这个明确限定的演示。真实项目如果有二级目录，应递归扫描，并把相对于资源根的路径纳入比较键；否则不同子文件夹里的同名图片会被误报。对符号链接、忽略名单、隐藏临时文件以及大小写不同的扩展名，也应该先写团队规则，再扩大适用范围。列表排序的价值并非提高运行速度，而是使改动前后的报告稳定。CI 里只要资源文件集相同，不该因枚举顺序变化产生噪声。这里的 Node.js 脚本属于构建前门禁，并不是官方的 DevEco 资源校验器，也不会替代 ArkTS 编译、资源索引生成及签名后的产物检查。## 三、两种错误，必须生成两种修复建议问题： 大小写碰撞与引用错配的修复动作不同。前者需要确认哪份资源才是唯一合法名称；后者需要统一“引用清单”和“实际文件”的拼写，不能一律改为小写。下面把两条规则独立实现：相同的小写键代表一个候选组，但只有组里出现两个以上不同的原始名字才认定为碰撞。javascriptfunction groupCaseCollisions(files) { const groups = new Map(); for (const name of files) { const key = name.normalize('NFC').toLowerCase(); const group = groups.get(key) ?? []; group.push(name); groups.set(key, group); } return [...groups.values()].filter((group) => group.length > 1);}function lintExactReferences(files, refs) { return refs.flatMap((ref) => { if (files.includes(ref)) return []; const found = files.find((name) => name.normalize('NFC').toLowerCase() === ref.normalize('NFC').toLowerCase()); return [{ ref, actual: found ?? null, reason: found ? 'CASE_MISMATCH' : 'MISSING_FILE' }]; });}````normalize('NFC')` 是为了减小部分 Unicode 组合形式的差异；`toLowerCase()` 也只是**保守的预检归并策略**，不是跨所有语言、平台和文件系统的严格大小写折叠规范。资源名若含特殊 Unicode 大小写映射，或者存在不同路径指向同一物理文件，就需要另行约束命名空间。可以规定资源文件名只允许 ASCII 字母、数字、下划线与明确的扩展名，再把复杂问题关在源头之外。例子中的 `Badge.svg` 和 `badge.svg` 被归到同一组，构成一条需要人工确定的修复任务；`userIcon.svg` 没有精确匹配，但能定位到 `UserIcon.svg`，输出的是另一条 `CASE_MISMATCH`。如果大小写忽略后也找不到实体，原因则应是 `MISSING_FILE`，不能假装它只是大小写拼写问题。扫描器输出“发现原因”，不自动改名，以免覆盖设计团队本来要保留的素材。![](https://i-blog.csdnimg.cn/direct/8c6b5f43bd4b4c7b833ef9581380e662.png)## 四、门禁应该阻断发布候选，不应该修改用户资源最后才建立总状态。这里的门禁不是应用启动时才弹出的红色提示，更不是在用户设备上扫描三方目录。它应发生在 CI 的资源准备阶段：先固化来源和清单，运行静态检查，发现问题就要求人工确认命名，再由正式构建验证结果。以下片段与前面的函数放在同一个 `.mjs` 文件即可组成演示脚本的核心流程。javascriptconst batchId = ‘CG-083’;const refs = [‘userIcon.svg’];const collisions = groupCaseCollisions(files);const misses = lintExactReferences(files, refs);const gate = collisions.length || misses.length ? ‘BLOCKED’ : ‘PASS’;const report = { batchId, files: files.length, collisionGroups: collisions.length, caseMisses: misses.length, gate};console.log(JSON.stringify(report, null, 2));process.exitCode = gate === ‘PASS’ ? 0 : 1;```代码的 process.exitCode 是 Node.js 进程退出码，用来交给外部 CI 判断，并非 ohpm 的专属参数。对设定的示例目录，期望报告是 CG-083、files=28、collisionGroups=1、caseMisses=1、BLOCKED。这是规则推导出的演示结果，不代表读者的组件安装后必然存在这些缺陷。若目录不存在，readdirSync() 会抛出异常，CI 应显示资源快照缺失并中止，不允许悄悄当作空集合通过。需要特别注意：有些发布链路在使用源码模块，有些则直接消费构建产物。若三方包只有 HAR、没有可审计的资源源码，本方案只能检查供应方提供的源快照或我方额外复制的资源；不能假定 HAR 里仍保留相同目录层级。官方关于 oh-package.json5 的文档明确列出本地 HAR、tgz、源码目录等依赖形态，不同形态需选择不同检查位置。## 五、把报告拿去复核，而不是把红字当结论为展示报告阅读方式，CaseGate 的演示页面保留批次号、资源数和两条问题，但真实工作流应在开发机或 CI 里运行脚本。第一条 Badge.svg / badge.svg 指向名称归并冲突；第二条 userIcon.svg → UserIcon.svg 指向引用拼写不一致。两条记录之外，不应推断图标一定在设备上丢失，或者构建一定失败。静态检查发现的是跨环境风险，最终失败与否还取决于具体构建、文件系统与资源打包方式。修复时，我会建议先选定唯一文件名，确认资源在所有引用点的实际语义，再统一修改与重新安装依赖；不要依赖系统“恰好容错”来放行。修改后应保留原始问题样本、扫描报告、工具版本和构建产物摘要，防止过几周再次出现同样的大小写漂移。资源数从二十八变为二十七或者引用清单更新，都要写清其业务原因，不能仅凭一个 PASS 字符串结束工作。这套小门禁真正有价值的地方，是把一个很容易混入“环境问题”的现象提前变成可讨论的证据：文件名碰撞、引用错配、正式构建结果是三件不同的事。当基础命名稳定，再谈第三方组件升级、主题适配、包体大小优化才有可靠起点。落地时需在实际操作系统、DevEco Studio、ohpm、目标 SDK 上重新验证；本文只展示可复现的 Node.js 静态规则，不声称 HarmonyOS 编译通过。官方参考： oh-package.json5 依赖配置；ohpm list 功能说明；HarmonyOS 开发者文档。