“只改了一个工具包版本，为什么打出来的包在另一台开发机上表现不一样？”三方库集成的问题经常不从业务代码开始，而是从依赖如何被声明、解析、安装和更新开始。把一个库加入 oh-package.json5，确实只需要改几行配置；但让它在多名开发者、多个构建节点之间稳定使用，需要给版本、来源、许可证和业务接口都划清界限。

这套连载围绕一个小型巡检应用之外的独立项目——内容卡片应用的三方依赖治理。它关注 ohpm 依赖准入、接口适配、构建排查及版本升级，不与前两套连载复用业务数据模型。第一篇先决定什么库可以引入、如何固定一个已批准版本，以及如何避免把第三方的调用细节散落到各个页面。

一个包有三种版本信息，混在一起就容易失控

对一个需要长期交付的 HarmonyOS 工程，至少区分三种信息：开发者写在 oh-package.json5 中的声明范围、ohpm 当前解析到的依赖树、最终提交并用于构建重现的锁文件。前两者并不天然相同。例如 ^2.0.0 允许匹配同一主版本中的后续兼容发布，而 2.0.0 是更明确的版本约束。锁文件记录当前安装求解结果，尤其能描述传递依赖的解析情况。只固定直接依赖却随意删除锁文件，仍然可能让不同构建时刻解析到不同的传递版本。

这里先选用华为官方“添加依赖项”文档出现的 @ohos/lottie 作为说明对象，不把动画能力当成本篇研究重点。@ohos/lottie 对应的真实 API 调用、适配设备、许可条款仍需在实际选型时单独审查；现在讨论的是如何把它作为有明确版本号的依赖条目接入模块。版本 2.0.0 用于说明版本固定语法，正式产品需要在目标仓库核实其可获取性、兼容性及许可证。

// entry/oh-package.json5 中的相关字段
{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
    "@ohos/lottie": "2.0.0"
  }
}

dependencies 是应用运行和编译所需的生产依赖；开发测试期间才需要的工具依赖可放在 devDependencies。如果是本地模块，官方提供 file:../folder 或 @module:moduleName 等写法。对于一般的远程三方库，不应为了图省事把所有依赖都塞进工程根目录；以实际引用它的模块为单位申明，更容易发现耦合范围，并可避免某些构建产物的依赖分析不一致。

准入不是“能装上”就算通过

安装成功只说明某个包可以被工具下载和解析，不等于它符合项目的技术、安全或授权要求。团队可以按以下顺序做判断：先确认包来自预期仓库或可追溯的本地 HAR；再核对版本是否支持目标 SDK 和 ArkTS 约束；然后查看许可证、维护状态、公开接口和传递依赖；最后才投入实际功能验证。若一个包要求应用开放与功能无关的权限，或者必须复制内部不稳定 API 才能工作，应该优先停在准入阶段，而不是把问题留给上线前修补。

这一阶段最重要的产出不是一个“可安装”按钮，而是一条可执行的审批规则。下面用 TypeScript 把库的准入事实与决策分开。DependencyPolicy 是项目内部业务类型，不冒充 ohpm 的系统 API；它的输入可以来自团队审核表，输出只代表业务准入规则，不能替代真实包的安全扫描、许可证核对或设备调试。

export interface DependencyPolicy {
  name: string;
  version: string;
  approvedVersion: string;
  licenseReviewed: boolean;
  sdkCompatible: boolean;
  hasOwner: boolean;
  needsUnexpectedPermission: boolean;
}

export interface GateDecision {
  allowed: boolean;
  reasons: string[];
}

export function evaluateDependency(item: DependencyPolicy): GateDecision {
  const reasons: string[] = [];
  if (item.name.trim().length === 0) {
    reasons.push('缺少包名称');
  }
  if (item.version !== item.approvedVersion) {
    reasons.push('当前版本与已审核版本不一致');
  }
  if (!item.licenseReviewed) {
    reasons.push('许可证尚未核对');
  }
  if (!item.sdkCompatible) {
    reasons.push('目标SDK兼容性尚未通过');
  }
  if (!item.hasOwner) {
    reasons.push('缺少内部维护负责人');
  }
  if (item.needsUnexpectedPermission) {
    reasons.push('存在与业务无关的额外权限要求');
  }
  return { allowed: reasons.length === 0, reasons };
}

const candidate: DependencyPolicy = {
  name: '@ohos/lottie',
  version: '2.0.0',
  approvedVersion: '2.0.0',
  licenseReviewed: false,
  sdkCompatible: false,
  hasOwner: true,
  needsUnexpectedPermission: false
};
const result: GateDecision = evaluateDependency(candidate);
// result.allowed === false；待完成许可证和SDK审查。

这里故意没有把所有布尔值都写成 true。阅读者不能因为示例代码运行出了“允许”，就误以为这个具体版本已经通过真实审核。版本一致性是必要条件，却不是充分条件。对三方库的兼容判断通常还包括 HarmonyOS 目标版本、设备形态、ArkTS 编译检查、工程构建模式，以及库对特定系统能力的权限需求。

将“锁定”落实到团队日常操作

先在 entry 模块的 oh-package.json5 中声明已经批准的准确版本，然后在工程根目录执行 ohpm install，让包管理工具安装依赖。依赖安装后，使用 ohpm list 查看直接依赖，必要时加 --depth 2 展开一部分依赖关系。实际项目应记录 ohpm 客户端版本，并把适用的 oh-package-lock.json5 纳入代码评审与版本管理，避免某位开发者无意重新求解传递依赖。

ohpm --version
ohpm install
ohpm list
ohpm list --depth 2

这里不建议用“删掉锁文件再试”作为首选排障方法。华为的 ohpm clean 文档明确写出它默认会同时清理 oh_modules 与锁文件；如确实需要清理安装产物但保留锁文件，应使用文档提供的 --keep-lockfile 选项，并先确认本地 ohpm 版本支持。清理是修复安装状态的一个动作，不是万能的升级策略。随意删除锁文件，相当于主动丢掉一部分构建重现依据。

# 检查锁文件已纳入版本控制后，才考虑清理本地安装产物
ohpm clean --keep-lockfile
ohpm install

如果代码评审只查看新增的一行版本号，最容易漏掉两类变化：一是传递依赖树发生了更新；二是模块级依赖被误加到工程级，导致在不同构建产物中行为不一致。建议提交中同时说明为什么升级、依赖树变化了什么、哪些业务组件受影响、失败时如何退回已知版本。这几行文字比“更新若干依赖”更有审计价值。

API适配边界，先设计再引入

即使同一个库在今天工作正常，也未必应该让几十个页面都直接导入它的类型。更稳妥的做法是业务页面依赖项目自身定义的适配接口，而第三方调用集中在适配器内部。比如内容卡片应用需要一个“播放资源动效”的业务能力，可以在本地抽象成 EffectDriver，页面只负责调用 start 和 stop；具体的 Lottie 或其他动画库接入代码留给适配器实现，这样升级时只需要调整一个边界，而不是在每个页面里查找方法名。

export interface EffectDriver {
  start(resourceId: string): Promise<void>;
  stop(): void;
}

export class CardEffectController {
  private driver: EffectDriver;
  private activeResource: string = '';

  constructor(driver: EffectDriver) {
    this.driver = driver;
  }

  async show(resourceId: string): Promise<void> {
    if (resourceId.trim().length === 0) {
      throw new Error('动效资源标识不能为空');
    }
    await this.driver.start(resourceId);
    this.activeResource = resourceId;
  }

  close(): void {
    this.driver.stop();
    this.activeResource = '';
  }

  current(): string {
    return this.activeResource;
  }
}

以上代码是业务适配契约，没有调用未经核实的第三方方法。真正集成时需要根据包的实际公开 API 编写适配实现，并在目标设备上确认生命周期、资源释放和错误处理方式。这样既满足核心业务模型的可阅读性，也避免把猜测的 playAnimation() 之类方法误写成库的公开能力。

一份能真正执行的准入检查

评审可以设置几个有代表性的样本：批准版本一致但许可证未核对，必须阻止准入；许可证和 SDK 都通过但版本被改成未经审核的新版本，必须阻止；版本与审批一致、许可证已核对、目标设备兼容、维护人明确且没有额外权限需求，才能进入功能测试阶段。这里“进入功能测试”不是“上线批准”，两者之间还要经过真实构建、资源占用、异常恢复与安全评估。

从错误定位角度看，首先区分下载失败、解析失败、编译失败、运行逻辑失败。下载失败先看仓库访问与包是否存在，解析失败核查依赖声明和锁文件，编译失败看 SDK、类型声明及工程模块边界，运行问题才进入实际三方 API 行为。把所有错误归咎为“这个库有问题”，会直接损失有效排查信息。

这一篇解决的是如何把三方库纳入治理，而不是如何写动画页面。下一阶段将围绕 EffectDriver 做真正的 ArkTS 接口适配，把依赖注入、错误传播、取消与资源释放隔离到明确的工程边界，继续保留今天确定的审批数据、版本策略和模块责任划分。

相关官方资料：华为开发者：添加依赖项、ohpm list 命令、ohpm clean 命令、ohpm version 命令。