# @azure/app-configuration 中文文档

规范地址：https://npmcn.com/package/%40azure/app-configuration/

版本：1\.13\.1
npm 元数据更新时间：2026-10-27T21:18:11.593Z
中文译文更新时间：2026-11-07T12:42:58.468Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40azure/app-configuration
原文对照：https://npmcn.com/package/%40azure/app-configuration/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

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

- 包体积（解压后）：2.6 MB，488 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：12 个
- 首次发布：2019-09-13T00:13:31.206Z
- 最新版本发布：2026-10-27T21:18:11.367Z
- 近 30 天下载量：873526（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：694（近 12 个月 76 个）

## 中文简介

Azure App 配置服务的同位素客户端库.

## 安装

```sh
npm install @azure/app-configuration
```

也可以使用：`pnpm add @azure/app-configuration`、`yarn add @azure/app-configuration`、`bun add @azure/app-configuration`

## README

# JavaScript 的 Azure App 配置客户端库

[Azure App 配置](https://learn.microsoft.com/azure/azure-app-configuration/overview) 是一种管理服务,帮助开发人员简单地和安全地集中其应用程序和功能设置.

密钥链接 :

-   [源代码](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/appconfiguration/app-configuration/)
-   [软件包( NPM)](https://www.npmjs.com/package/@azure/app-configuration)
-   [API 参考文件](https://learn.microsoft.com/javascript/api/@azure/app-configuration)
-   [产品文档](https://learn.microsoft.com/azure/azure-app-configuration/)
-   [样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples)

## 选择正确的软件包

使用 _@ azure/ app- 配置_ (本图书馆)改为:

-   在 Azure App 配置中管理配置设置和快照
-   执行正常配置消耗范围以外的颗粒读取

大多数应用程序应该从 [_@ azure/ app- configration- 提供者_](https://www.npmjs.com/package/@azure/app-configuration-provider) 库,它基于这个低级客户端库,是运行时消费配置的建议方式. 它补充说:

-   使用配置作为密钥/ 值图或结构化 JSON 对象的灵活访问模式
-   解析应用程序配置的查询机制
-   运行时刷新配置
-   具有高可靠性的缓存、复制发现、故障和负载平衡
-   密钥库参考解析和自动更新
-   特性旗集成 [@ 微软/ 地貌管理](https://www.npmjs.com/package/@microsoft/feature-management) 图书馆

欲了解更多信息,请前往 [配置提供者概览](https://learn.microsoft.com/azure/azure-app-configuration/configuration-provider-overview)。 。 。 .

## 开始

### 安装软件包

```bash
npm install @azure/app-configuration
```

**说明:** 对于申请 **只需要读取配置值**我们建议使用 [_@ azure/ app- configration- 提供者_](https://www.npmjs.com/package/@azure/app-configuration-provider) 图书馆.

### 目前得到支持的环境

-   [节点.js的LTS版本](https://github.com/nodejs/release#release-schedule)
-   Safari,Chrome,Edge,和Firefox的最新版本.

看我们的 [支助政策](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md) 更多细节.

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/)
-   一个 [App 配置](https://learn.microsoft.com/azure/azure-app-configuration/) 资源

### 创建 App 配置资源

你可以用这个 [Azure 门户](https://portal.azure.com/) 或 [阿苏尔CLI](https://learn.microsoft.com/cli/azure) 创建 Azure App 配置资源.

示例(Azure CLI):

```
az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus
```

### 认证客户端

AppConfigation 客户端可以使用 [服务本金](https://npmcn.com/package/%40azure/app-configuration/#readme-authenticating-with-a-service-principal) 或使用 [连接字符串](https://npmcn.com/package/%40azure/app-configuration/#readme-authenticating-with-a-connection-string)。 。 。 .

#### 使用服务本金认证

通过服务本金进行认证的方式如下:

-   使用 `@azure/identity` 软件包.
-   在您的配置资源上设定相应的 RBAC 规则 . 关于 App 配置角色的更多信息可以找到 [这里](https://learn.microsoft.com/azure/azure-app-configuration/concept-enable-rbac#azure-built-in-roles-for-azure-app-configuration)。 。 。 .

使用 [默认标记](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#defaultazurecredential)

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
```

更多关于 `@azure/identity` 可见 [这里](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md)

#### 主权云

用资源认证 a [主权云](https://learn.microsoft.com/azure/active-directory/develop/authentication-national-cloud),您需要设置 `audience` 输入 `AppConfigurationClient` 构造器选项 .

```ts
import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});
```

注:何时 `audience` 未定义属性, SDK 将默认为 Azure Public Cloud .

#### 正在使用连接字符串认证

要得到小学 **连接字符串** 对于 App 配置资源, 您可以使用此 Azure CLI 命令 :

```
az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"
```

您可以在代码中创建您的 App 配置客户端 **连接字符串** 你从AzureCLI得到:

```ts
import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);
```

## 关键概念

这个 [`AppConfigurationClient`](https://learn.microsoft.com/javascript/api/@azure/app-configuration/appconfigurationclient) 从门户网站的 App 配置中有一些术语变化 .

-   键/等值对表示为 [`ConfigurationSetting`](https://learn.microsoft.com/javascript/api/@azure/app-configuration/configurationsetting) 对象
-   锁定和解锁一个设置在 `isReadOnly` 字段,可以切换 `setReadOnly`。 。 。 .
-   抓图显示为 `ConfigurationSnapshot` 对象.

客户采用简单的设计方法 [`ConfigurationSetting`](https://learn.microsoft.com/javascript/api/@azure/app-configuration/configurationsetting) 能够传递到任何一种方法 [`ConfigurationSettingParam`](https://learn.microsoft.com/javascript/api/@azure/app-configuration/configurationsettingparam) 或者说 [`ConfigurationSettingId`](https://learn.microsoft.com/javascript/api/@azure/app-configuration/configurationsettingid)。 。 。 .

这意味着这个模式的工作:

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const setting = await client.getConfigurationSetting({
  key: "hello",
});

setting.value = "new value!";
await client.setConfigurationSetting(setting);

// fields unrelated to just identifying the setting are simply
// ignored (for instance, the `value` field)
await client.setReadOnly(setting, true);

// delete just needs to identify the setting so other fields are
// just ignored
await client.deleteConfigurationSetting(setting);
```

或,例如,重新设置:

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

let setting = await client.getConfigurationSetting({
  key: "hello",
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);
```

这个 `2022-11-01-preview` API版本支持配置快照:不可变,即时复制一个配置商店. 可使用确定快照中包含哪些密钥值对的过滤器来创建快照,从而创建一个由配置库构成的不可改变的视图. 这个特性使应用程序能够持有一致的配置视图,确保不会因为更新时的读取而使版本不匹配到单个设置. 例如,这个功能可用于在App配置中创建"释放配置快照". 见 [页:1 _创建并获得快照_ 节](https://npmcn.com/package/%40azure/app-configuration/#readme-create-and-get-a-setting) 以下文为例.

## 实例

**说明:** 如果您的应用程序仅需要检索配置值而不需要执行配置设置上的创建、更新或删除操作,请考虑使用 [_@ azure/ app- configration- 提供者_](https://www.npmjs.com/package/@azure/app-configuration-provider) 图书馆。 提供者库为在运行时加载配置数据提供了简化的经验 [其他特性](https://learn.microsoft.com/azure/azure-app-configuration/configuration-provider-overview#feature-development-status)您可以在 Azure App 配置文档中找到许多代码样本 [微软学习](https://learn.microsoft.com/azure/azure-app-configuration/quickstart-javascript-provider)。 。 。 .

### 创建并获得一个设置

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.setConfigurationSetting({
  key: "testkey",
  value: "testvalue",
  // Labels allow you to create variants of a key tailored
  // for specific use-cases like supporting multiple environments.
  // https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
  label: "optional-label",
});

const retrievedSetting = await client.getConfigurationSetting({
  key: "testkey",
  label: "optional-label",
});

console.log("Retrieved value:", retrievedSetting.value);
```

### 创建快照

`beginCreateSnapshot` 让传票人去调查快照的制作.

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

await client.addConfigurationSetting({
  key,
  value,
  label,
});

const poller = await client.beginCreateSnapshot({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();
```

您还可以使用 `beginCreateSnapshotAndWait` 在投票结束后直接获得创作结果.

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const snapshot = await client.beginCreateSnapshotAndWait({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});
```

### 获取快照

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);
```

### 列出 `ConfigurationSetting` 在快照内

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}
```

### 列出服务中的所有快照

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

for await (const snapshot of snapshots) {
  console.log(`Found snapshot: ${snapshot.name}`);
}
```

### 恢复并归档快照

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);
```

## 解决问题

### 日志

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 `AZURE_LOG_LEVEL` 环境变量改为 `info`。或者,可以在运行时拨打 `setLogLevel` 输入 `@azure/logger`数字 :

```ts
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```

关于如何启用日志的更详细指示,您可以查看 [@ azure/ logger 包文件](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger)。 。 。 .

### 反应原生支持

React Introduct不支持这个SDK库使用的一些JavaScript API,所以需要为他们提供多填充. 请看我们的 [以 Expo 反应原生样本](https://github.com/Azure/azure-sdk-for-js/blob/main/samples/frameworks/react-native/appconfigBasic/README.md#add-polyfills) 更多细节.

## 今后的步骤

下列样本显示您可以与 App 配置交互的各种方式 :

-   [`helloworld.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/helloworld.ts) - 获取、设定和删除配置值.
-   [`helloworldWithLabels.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/helloworldWithLabels.ts) - 使用标签在设置中添加额外的维度,以适应 beta vs 生产等情况.
-   [`optimisticConcurrencyViaEtag.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/optimisticConcurrencyViaEtag.ts) - 使用etags设定值,以防止意外覆盖.
-   [`setReadOnlySample.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/setReadOnlySample.ts) - 标记设置为只读,以防止修改.
-   [`getSettingOnlyIfChanged.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/getSettingOnlyIfChanged.ts) - 得到一个设定,除非它改变 从上次你得到它.
-   [`listRevisions.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/listRevisions.ts) - 列出一个密钥的修订, 允许您看到以前的值和设定时的值 .
-   [`secretReference.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/secretReference.ts) - 秘密参考 代表一个配置设置, 引用为 KeyVault 密钥 .
-   [`snapshot.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/snapshot.ts) - 创建、列表配置设置和归档快照.
-   [`featureFlag.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/featureFlag.ts) - 特性标记是遵循特定 JSON 值的设置.

更深入的例子可见于本报告 [样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/) gitHub 上的文件夹.

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) 学习如何构建和测试密码.

这个模块的测试是现场测试和单元测试的混合,这需要您有一个Azure App配置实例. 执行测试需要运行:

1.  `pnpm install`
2.  `pnpm build --filter @azure/app-configuration...`
3.  创建 .env 文件,其中包含这些内容 `sdk\appconfiguration\app-configuration` 文件夹 : `APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance`
4.  `cd sdk\appconfiguration\app-configuration`
5.  `npm run test`。 。 。 .

查看我们的 [测试](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/appconfiguration/app-configuration/test) 详细文件夹.

## 相关项目

-   [微软 Azure SDK 用于 JavaScript](https://github.com/Azure/azure-sdk-for-js)
-   [Azure App 配置](https://learn.microsoft.com/azure/azure-app-configuration/overview)

## 常见问题

### @azure/app-configuration 是什么？

Azure App 配置服务的同位素客户端库\.

### 如何安装 @azure/app-configuration？

在项目目录运行 npm install @azure/app-configuration，或使用 pnpm add / yarn add / bun add。

### @azure/app-configuration 支持 TypeScript 吗？

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

### @azure/app-configuration 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/app-configuration 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/app-configuration 可以商用吗？

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

### @azure/app-configuration 的下载量有多少？

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

### @azure/app-configuration 还在维护吗？

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