# @azure/msal-node-extensions 中文文档

规范地址：https://npmcn.com/package/%40azure/msal-node-extensions/

版本：5\.6\.1
npm 元数据更新时间：2026-11-06T23:51:36.895Z
中文译文更新时间：2026-11-07T13:15:56.507Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40azure/msal-node-extensions
原文对照：https://npmcn.com/package/%40azure/msal-node-extensions/?lang=original
项目主页：https://github.com/AzureAD/microsoft-authentication-library-for-js#readme
源码仓库：https://github.com/AzureAD/microsoft-authentication-library-for-js

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

- 包体积（解压后）：841 kB，110 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2020-07-13T20:59:14.601Z
- 最新版本发布：2026-11-06T23:51:36.720Z
- 近 30 天下载量：1598207（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：135（近 12 个月 41 个）

## 中文简介

![npm (scoped)](https://img.shields.io/npm/v/@azure/msal-node-extensions) ![npm](https://img.shields.io/npm/dw/@azure/msal-node-extensions)

## 安装

```sh
npm install @azure/msal-node-extensions
```

也可以使用：`pnpm add @azure/msal-node-extensions`、`yarn add @azure/msal-node-extensions`、`bun add @azure/msal-node-extensions`

## README

# 微软认证节点扩展

![npm (scoped)](https://img.shields.io/npm/v/@azure/msal-node-extensions) ![npm](https://img.shields.io/npm/dw/@azure/msal-node-extensions)

| [开始](https://docs.microsoft.com/azure/active-directory/develop/tutorial-v2-react) | [AAD 文档](https://aka.ms/aaddevv2) | [图书馆参考文献](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_react.html) | [样本](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples) |
| --- | --- | --- | --- |

1.  [关于](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-about)
    -   [缓存持久性](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-cache-persistence)
    -   [经纪活动](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-brokering)
2.  [财务问题](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/extensions/docs/faq.md)
3.  [更改日志](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/extensions/msal-node-extensions/CHANGELOG.md)
4.  [先决条件](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-prerequisites)
5.  [安装](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-installation)
6.  [用法 - 缓存持久性](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-usage---cache-persistence)
7.  [用法 - 经纪](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-usage---brokering)
8.  [构建和测试](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-build-and-test)
    -   [构建软件包](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-building-the-package-locally)
    -   [测试包](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-running-tests)
9.  [样本](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-samples)
10.  [安全报告](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-security-reporting)
11.  [许可证](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-license)
12.  [捐款](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-contributing)
13.  [行为守则](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-we-value-and-adhere-to-the-microsoft-open-source-code-of-conduct)

## 关于

这个 `msal-node-extensions` 图书馆提供可选的功能,以加强 `msal-node`数字 :

-   客户端应用程序执行跨平台缓存序列化和持久性的安全机制
-   用于从本地代币经纪人处获取代币的接口,可与其他本地应用程序实现更高程度的安全和SSO

### 缓存持久性

[MSAL 节点](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node) 默认支持内存缓存,并提供ICachePlugin接口来进行缓存序列化,但并不提供默认将令牌缓存存储到磁盘的方法. 微软的节点认证扩展是针对持续缓存到不同平台的磁盘的默认执行.

支持的平台有:Windows,Mac和Linux:

-   Windows - DPAPI用于加密.
-   MAC - MAC KeyChain被使用.
-   Linux - LibSecret用于存储到"Secret Service".

> 注意:建议使用此库用于缓存持续支持公共客户端应用程序,如只用于桌面应用程序. 在网络应用中,这可能导致规模和性能问题. 建议Web应用程序在会话中坚持缓存.

### 经纪活动

当使用本地经纪人时,刷新令牌被绑定在它们被购买的设备上,并且不能被访问 `msal-node` 或申请。 这提供了更高的安全水平,无法通过 `msal-node` 一个人 有关代币经纪的更多信息可以找到 [这里](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node/docs/brokering.md)

## 先决条件

这个 `msal-node-extensions` 有预编二进制的图书馆船.

> 注意: 如果您正计划在 msal- node- extensions 上进行本地开发, 您可能需要安装一些额外的工具 . [节点-gyp](https://github.com/nodejs/node-gyp) 用于编译 [加词](https://nodejs.org/api/addons.html) 用于访问系统 API。 安装需求列于 [节点- gyp 读取](https://github.com/nodejs/node-gyp#installation)

在linux上,库使用 `libsecret` 所以你可能需要安装它。 根据您的分布, 您需要运行以下命令 :

-   德比安/乌班图: `sudo apt-get install libsecret-1-dev`
-   红帽型: `sudo yum install libsecret-devel`
-   Arch Linux: sudo (中文(简体) ) `pacman -S libsecret`

## 安装

这个 `msal-node-extensions` 国家防范机制有一套软件包.

```bash
npm i @azure/msal-node-extensions --save
```

## 用法 - 缓存持久性

### 开始

这里有一个代码片段,介绍如何配置符号缓存 .

```js
const { 
    DataProtectionScope,
    Environment,
    PersistenceCreator,
    PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

// You can use the helper functions provided through the Environment class to construct your cache path
// The helper functions provide consistent implementations across Windows, Mac and Linux.
const cachePath = path.join(Environment.getUserRootDirectory(), "./cache.json");

const persistenceConfiguration = {
    cachePath,
    dataProtectionScope: DataProtectionScope.CurrentUser,
    serviceName: "<SERVICE-NAME>",
    accountName: "<ACCOUNT-NAME>",
    usePlaintextFileOnLinux: false,
}

// The PersistenceCreator obfuscates a lot of the complexity by doing the following actions for you :-
// 1. Detects the environment the application is running on and initializes the right persistence instance for the environment.
// 2. Performs persistence validation for you.
// 3. Performs any fallbacks if necessary.
PersistenceCreator
.createPersistence(persistenceConfiguration)
.then(async (persistence) => {
    const publicClientConfig = {
        auth: {
            clientId: "<CLIENT-ID>",
            authority: "<AUTHORITY>",
        },

        // This hooks up the cross-platform cache into MSAL
        cache: {
            cachePlugin: new PersistenceCachePlugin(persistence)
        }
    };

    const pca = new msal.PublicClientApplication(publicClientConfig);
    
    // Use the public client application as required...
});
```

关于持久性配置的所有论据解释如下:

| 字段名称 | 说明 | 所需时间 |
| --- | --- | --- |
| 缓存Path | 这是库用来同步读取和写入的锁文件的路径 | 视窗、Mac和Linux |
| 数据保护范围 | 指定当前用户或本地机上的数据保护范围. | 窗口 |
| 服务Name | 此指定用于 Mac 和/ 或 Linux 的服务名称 | 麦克和Linux |
| 账户Name | 此指定用于 Mac 和/ 或 Linux 的账户名称 | 麦克和Linux |
| 使用 PlaintextFileOnLinux 软件 | 如果 libsecret 失败, 此旗帜将默认为 linux 上的纯文本 。 默认为 `false` | 链接 |

### 安全边界

在Windows和Linux上,令牌缓存被扩展为用户会话,即代表用户运行的所有应用程序都可以访问缓存. Mac提供了更受限制的范围,确保只有创建缓存的应用程序才能访问它,如果其他人的应用程序想要访问,则会提示用户.

## 用法 - 经纪

促成代币经纪只需要一个新的配置参数:

```javascript
import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id"
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin()
    }
};

const pca = new PublicClientApplication(msalConfig);
```

更详细的资料见本文件附件 [中介文件](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node/docs/brokering.md)

## 构建和测试

若您打算为图书馆的参观捐款 [`contributing section`](https://npmcn.com/package/%40azure/msal-node-extensions/#readme-contributing) 更需要更多关于如何操作的信息.

### 在当地建立软件包

来建造两个 `@azure/msal-node-extensions` 图书馆和图书馆 `@azure/msal-common` 库,运行下列命令:

```bash
// Install dev dependencies from root of repo
npm install
// Change to the msal-node-extensions package directory
cd lib/msal-node-extensions/
// Build msal-common and msal-node-extensions
npm run build:all
```

### 运行测试

`@azure/msal-node-extensions` 用途 [欢笑](https://jestjs.io/) 进行单位测试和覆盖.

```bash
// To run tests
npm test
```

## 样本

-   [带有缓存持久性的 Auth Code CLI 样本](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/extensions/samples/msal-node-extensions)。可以在Windows、Mac和Linux上运行.
-   [带有缓存持久性的电样](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/extensions/samples/electron-webpack)
-   [经纪样本](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code-cli-brokered-app)

## 安全报告

如果你发现我们的图书馆或服务有安全问题,请报告 [安全性@ microsoft.com](mailto:secure@microsoft.com) 尽可能详细。 您的呈文可能有资格通过 [微软慷慨](http://aka.ms/bugbounty) 程序。 请不要将安全问题张贴到 GitHub 问题或任何其他公共网站。 我们收到消息后马上联系你 我们鼓励您通过访问了解安全事件何时发生 [此页面](https://technet.microsoft.com/security/dd252948) 并签署安全咨询警报.

## 许可证

版权 (c) 微软公司。 版权所有。 根据麻省理工学院的许可.

## 捐款

该项目欢迎各方的贡献和建议。 大多数捐款要求您同意 撰稿人许可协议(CLA)宣布,你有权并且实际上确实给了我们 有权使用您的贡献。 详情请访问 [https://cla.opensource.microsoft.com 互联网档案馆的存檔,存档日期2014-10-02](https://cla.opensource.microsoft.com/)。 。 。 .

当您提交拉拉请求时, CLA bot 会自动确定您是否需要提供 a CLA并适当装饰PR(如状态检查、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成.

该项目通过了 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息见 [《行为守则》](https://opensource.microsoft.com/codeofconduct/faq/) 或者说 联系人 [打开码@ microsoft.com](mailto:opencode@microsoft.com) 并附上任何其他问题或评论.

## 我们重视并遵守微软开放源码行为守则

该项目通过了 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。更多信息见 [《行为守则》](https://opensource.microsoft.com/codeofconduct/faq/) 或联系人 [打开码@ microsoft.com](mailto:opencode@microsoft.com) 并附上任何其他问题或评论.

## 常见问题

### 如何安装 @azure/msal-node-extensions？

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

### @azure/msal-node-extensions 支持 TypeScript 吗？

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

### @azure/msal-node-extensions 支持 ESM 还是 CommonJS？

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

### @azure/msal-node-extensions 需要什么版本的 Node\.js？

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

### @azure/msal-node-extensions 可以商用吗？

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

### @azure/msal-node-extensions 的下载量有多少？

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

### @azure/msal-node-extensions 还在维护吗？

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