# @contentauth/c2pa-utilities 中文文档

规范地址：https://npmcn.com/package/%40contentauth/c2pa-utilities/

版本：0\.4\.0
npm 元数据更新时间：2026-11-03T23:52:42.134Z
中文译文更新时间：2026-11-10T16:32:36.614Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40contentauth/c2pa-utilities
原文对照：https://npmcn.com/package/%40contentauth/c2pa-utilities/?lang=original
项目主页：https://github.com/contentauth/c2pa-js#readme
源码仓库：https://github.com/contentauth/c2pa-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：94.7 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-08-14T21:25:51.333Z
- 最新版本发布：2026-11-03T23:52:41.760Z
- 近 30 天下载量：495523（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

`c2pa-utilities` 共用公用设施和图书馆 `c2pa-web` 财务报告和审定财务报表 `c2pa-node`. 多数客户都会作为其中之一的依赖性而获得这些转接,但 `@contentauth/c2pa-utilities` 还发布独立文件

## 安装

```sh
npm install @contentauth/c2pa-utilities
```

也可以使用：`pnpm add @contentauth/c2pa-utilities`、`yarn add @contentauth/c2pa-utilities`、`bun add @contentauth/c2pa-utilities`

## README

# c2帕-用途

`c2pa-utilities` 共用公用设施和图书馆 `c2pa-web` 财务报告和审定财务报表 `c2pa-node`. 多数客户都会作为其中之一的依赖性而获得这些转接,但 `@contentauth/c2pa-utilities` 也可以针对您想要直接重用其中的一部分的情况单独发布.

## 安装

```sh
npm install @contentauth/c2pa-utilities
```

## API 参考文件

从 TypeScript 源生成完整的 API 文档 [类型文件](https://typedoc.org/) 并出版给 [GitHub 页面](https://contentauth.github.io/c2pa-js/modules/_contentauth_c2pa-utilities.html)。 。 。 .

## 公用事业

### `Context` 财务报告和审定财务报表 `Settings`

`Settings` 是一个简单的,JSON的可串行对象,围绕信任锚,验证选项来配置SDK行为,以及 `Reader`编号 :`Builder` 选项.

`Context` 是一个小而不可改变的包装 `Settings`,是建议配置 `Reader`编号 :`Builder`。 。 。 . `Context` 对象直接传递到创建 `Reader`编号 :`Builder` 实例,所以运行 SDK 实例可以自由创建许多不同的 `Reader`编号 :`Builder`s,每个都有自己的 `Context`。 。 。 . `Context` 变化不宣传,因为 `Context` 当用于构建一个 `Reader`编号 :`Builder`因此,它可以安全地用于构建多个实例.

见 [`c2pa-web`读取](https://npmcn.com/package/%40contentauth/c2pa-web/README.md#configuring-behavior-with-context) 举个例子.

#### 创建一个 `Context`

```typescript
import { Context } from '@contentauth/c2pa-utilities';

const context = new Context({
  verify: {
    verifyTrust: true
  },
  trust: {
    trustAnchors: 'https://example.com/trust-anchors.pem'
  }
});
```

#### 组合 `Settings`

每个 `Context` 持有任何单一 `Settings` 对象被传递到其构建器,不处理任何设置的合并。 合并多个 `Settings` 源代码,先将它们合并到 `mergeSettings()`,然后构造一个 `Context` 从单一,合并的结果:

```typescript
import { Context, mergeSettings } from '@contentauth/c2pa-utilities';

const base = { verify: { verifyTrust: true } };
const override = { verify: { verifyAfterSign: true } };

const context = new Context(mergeSettings(base, override));
// context.settings is { verify: { verifyTrust: true, verifyAfterSign: true } }
```

#### 解决a `Context` 给 JSON 的

设置通过 WASM(`c2pa-web`)/本土(`c2pa-node`作为JSON字符串的边界. `toJson()` 解决设置中嵌入的任何信任锁定器 URL( 比较并验证它们) , 并将结果序列化 :

```typescript
const contextJson = await context.toJson();
// '{"verify":{"verify_trust":true},"trust":{"trust_anchors":"-----BEGIN CERTIFICATE-----..."}}'
```

此步骤是同步的,如果信任锁定器 URL 无法解决,则可以丢出 。 捆绑者称它一次,就在建基地之后 `Context`,而不是在每一个 `Reader`编号 :`Builder` 电话 内部, `toJson()` 是薄薄的包装 `resolveSettings`页:1.

#### 大楼 `Settings` 直接

`Context` 建立在少数低层之上 `Settings` 帮助者,在不需要帮助的情况下仍可直接使用 `Context` 完全没有:

```typescript
import {
  createTrustSettings,
  createVerifySettings,
  mergeSettings,
  resolveSettings
} from '@contentauth/c2pa-utilities';

const trustSettings = createTrustSettings({
  trustAnchors: 'https://example.com/anchors.pem'
});

const verifySettings = createVerifySettings({
  verifyTrust: true,
  verifyAfterReading: true
});

const settings = mergeSettings(trustSettings, verifySettings);

// Resolves trust-anchor URLs and serializes to the snake_case JSON string the native SDK expects.
const settingsJson = await resolveSettings(settings);
```

`resolveSettings` 最直接的呼叫者想要的切入点。 它解决任何 `trust`编号 :`cawgTrust` URL字段(对 PEM 内容进行比对并内置,重试瞬间失败),并以蛇相JSON字符串返回结果. `settings` 在此包的默认值之上合并, 所以 `resolveSettings` 总是返回一个值, 即使调用 `undefined`。合并多个 `Settings` 对象先合并到 `mergeSettings()` 打电话前 `resolveSettings`,如上. (中文(简体) ).

其他出口:

-   `createTrustSettings` 编号 : `createCawgTrustSettings` 编号 : `createVerifySettings` - 建造一个 `Settings` 用于一节的片段.
-   `mergeSettings` ——深陷于任何数量 `Settings` 片段,后面的争论压倒了前面的争论. 被嵌入的田被合并而不是被覆盖.
-   `settingsToJson` 序列化a `Settings` 对象为它的蛇 case JSON 格式,而不解决信任-锁定 URL .
-   `snakeCaseify` – 下等骆驼 Case- snake case 对象转换器 `settingsToJson`编号 :`resolveSettings` 内部使用.
-   `loadSettingsFromUrl` 从 URL 获取一个设置 JSON 文档, 并重试 .
-   `resolveTrustSettings` 决心只是 `TrustSettings` 对象的 URL 字段已设置; 内部使用 `resolveSettings`。 。 。 .

### 用重试获取

`fetchWithRetry` 财务报告和审定财务报表 `fetchWithRetryRaw` 关闭 `fetch` 与指数反射, `Retry-After` 处理和(用于) `fetchWithRetry`反应大小上限。 重试机制是固定的;然而,政策细节,如重试计数、倒计时、可重试的状态/误差以及最高荣誉 `Retry-After` 通过 `FetchWithRetryOptions`。 。 。 .

```typescript
import { fetchWithRetry, fetchWithRetryRaw } from '@contentauth/c2pa-utilities';

// GET as text, retrying on network errors, 429, and 5xx, capped at 1 MB by default.
const text = await fetchWithRetry('https://example.com/anchors.pem');

// For other methods, headers, or bodies, or to handle the response yourself, use fetchWithRetryRaw.
const response = await fetchWithRetryRaw('https://example.com/upload', {
  method: 'POST',
  body: payload
});
```

两个函数都接受 `FetchWithRetryOptions` 更改默认值时的对象 :

```typescript
await fetchWithRetry(url, {
  maxRetries: 5,
  initialRetryDelayMs: 500,
  maxRetryDelayMs: 5_000,
  maxRetryAfterMs: 60_000,
  maxResponseBytes: 5 * 1024 * 1024,
  isRetryableStatus: (status) => status === 429 || status >= 500,
  isRetryableError: (error) => true,
  fetch: myFetchImplementation
});
```

一个 `AbortError` 永远不要重试, 错误的 URL 会立即丢出而不是重试.

### 资产规模验证

`validateAssetSize` 是两者使用的共享大小检查 `Reader` 在读取资产之前执行.

```typescript
import { validateAssetSize, AssetTooLargeError, DEFAULT_MAX_SIZE_IN_BYTES } from '@contentauth/c2pa-utilities';

try {
  validateAssetSize(sizeInBytes, maxSizeInBytes); // pass 0 to use DEFAULT_MAX_SIZE_IN_BYTES
} catch (e) {
  if (e instanceof AssetTooLargeError) {
    // asset exceeds the resolved limit
  }
}
```

### 签名算法

`SigningAlg` 是核心本地库在签名人构建边界(如:. `Signer.newSigner(cert, key, alg)`) (中文(简体) ). 来源于PascalCase `SigningAlg` 导出者 `@contentauth/c2pa-types`,它描述一个清单时使用的外壳 `SignatureInfo.alg` 被序列化.

## 图书馆发展

### 先决条件

确保安装全覆盖的先决条件:

-   补丁 [节点.js](https://nodejs.org/) 释放;见 [TLS 信托基金](https://npmcn.com/package/README.md#tls-trust-stores)。 。 。 .
-   [无](https://nx.dev/getting-started/intro)
-   [小时](https://pnpm.io/)

见 [捐助的先决条件](https://github.com/contentauth/c2pa-js/blob/main/docs/project-contributions.md#prerequisites) 详细情况.

### 大楼

为建设:

```sh
nx build c2pa-utilities
```

### 测试

此库使用 [维特](https://vitest.dev/),与 [质量](https://mswjs.io/) 来嘲笑 `fetch` 在设置和检索中进行重试.

为了进行测试:

```sh
nx test c2pa-utilities
```

## 常见问题

### @contentauth/c2pa-utilities 是什么？

c2pa-utilities 共用公用设施和图书馆 c2pa-web 财务报告和审定财务报表 c2pa-node\. 多数客户都会作为其中之一的依赖性而获得这些转接,但 @contentauth/c2pa-utilities 还发布独立文件

### 如何安装 @contentauth/c2pa-utilities？

在项目目录运行 npm install @contentauth/c2pa-utilities，或使用 pnpm add / yarn add / bun add。

### @contentauth/c2pa-utilities 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @contentauth/c2pa-utilities 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @contentauth/c2pa-utilities 可以商用吗？

@contentauth/c2pa-utilities 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @contentauth/c2pa-utilities 的下载量有多少？

根据 npm 官方下载统计，@contentauth/c2pa-utilities 在 2026/10/11 – 2026/11/09 这 30 天内被下载 495,523 次，日均约 16,517 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @contentauth/c2pa-utilities 还在维护吗？

最新版本 0\.4\.0 发布于 2026/11/04（6 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/08/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。