# @azure-tools/azcopy-node 中文文档

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

版本：3\.4\.15
npm 元数据更新时间：2026-04-08T00:58:57.664Z
中文译文更新时间：2026-11-07T14:20:51.549Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40azure-tools/azcopy-node
原文对照：https://npmcn.com/package/%40azure-tools/azcopy-node/?lang=original
项目主页：https://github.com/Azure/azure-storage-azcopy#readme
源码仓库：https://github.com/Azure/azure-storage-azcopy

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

- 包体积（解压后）：131 kB，74 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2020-07-31T18:47:03.921Z
- 最新版本发布：2026-04-08T00:58:57.492Z
- 近 30 天下载量：21250（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 1 个）

## 中文简介

此软件包允许您引用 [AzCopy v 10 (英语)](https://github.com/Azure/azure-storage-azcopy) 从NodeJS.

## 安装

```sh
npm install @azure-tools/azcopy-node
```

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

## README

# Azcopy 节点

此软件包允许您引用 [AzCopy v 10 (英语)](https://github.com/Azure/azure-storage-azcopy) 从NodeJS.

## 基本用途

```js
const { AzCopyClient } = require("@azure-tools/azcopy-node");
let client = new AzCopyClient();

// AzCopy is used to move things from one location to another.
let src = /* a `AzCopyLocation` */;
let dst = /* a `AzCopyLocation` */;

// All functions that start AzCopy jobs return a job ID.
let jobId = await client.copy(src, dst);

let status;
// You use this job ID to check on the progress of your job, and know if it has finished.
while (!status || status.StatusType !== "EndOfJob") {
    let jobInfo = await copyClient.getJobInfo(jobId)
    status = jobInfo.latestStatus;
    await new Promise((resolve, reject) => setTimeout(resolve, 1000));
}

```

## 在哪里找到 AzCopy 可执行文件

AzCopy可执行文件可在国家防范机制上提供,用于Windows(32和64位)、macOS和Linux。 此软件包已经声明其中每个都是可选的依赖性 。 确切的包裹有:

-   [@azure-tools/azopy-win32 (韩语)](https://www.npmjs.com/package/@azure-tools/azcopy-win32)
-   [@azure-tools/azcopy-win64 (韩语)](https://www.npmjs.com/package/@azure-tools/azcopy-win64)
-   [@azure-tools/azcopy-win-arm64 (韩语)](https://www.npmjs.com/package/@azure-tools/azcopy-win-arm64)
-   [@azure-tools/ azcopy-linux (缩写)](https://www.npmjs.com/package/@azure-tools/azcopy-linux)
-   [@azure-tools/ azcopy- darwin (韩语)](https://www.npmjs.com/package/@azure-tools/azcopy-darwin)
-   [@azure-tools/azcopy-darwin-arm64 (韩语)](https://www.npmjs.com/package/@azure-tools/azcopy-darwin-arm64)

它们是可选的依赖性,因为每个软件包都声明自己只对它打算使用的OS有效. 这意味着当你逃跑时 `npm install` 只安装您当前运行的 OS 的 AzCopy 可执行文件 .

如果您想要安装所有版本, 您可以使用 `--force` 旗帜为 `npm install`。 。 。 .

## 指定要使用的 AzCopy 可执行文件

默认, `AzCopyClient` 将使用最符合您的操作系统和架构的 @azure-tools AzCopy 可执行软件包。 使用不同的可执行文件有两种可能性:

1.  如果可用, 使用不同架构的@ azure- tools AzCopy 可执行软件包( bit-ness)
2.  使用自定义 AzCopy 可执行文件

对于第一种情景,如果想要强制运行64bit可执行文件的32bit,您可以指定一个 `bitness` 在 AzCopyClient 构造器的选项对象中。 由于Windows是唯一一个同时提供32位和64位可执行文件的OS,这实际上只是Windows需要考虑的事情.

第二种情况你可以使用 `exe` azCopyClient 构造器在选项对象中指定自定义 AzCopy 可执行文件的路径。 如果你这样做,有两件事要知道:

1.  此软件包以AzCopy的特定版本进行校验. 建议不使用不同的版本。 如果决定这样做,请确保适当测试和核实.
2.  当使用一个 `IRemoteAuthLocation`,您不能在 Linux 上使用 AzCopy 的非 NPM 版本。 @azure-tools/azcopy-linux中的AzCopy使用AzCopy的特殊建筑.

## Azure AD 设想方案

当你使用一个 `IRemoteAuthLocation`, azcopy-node 必须与运行中的 AzCopy 可执行文件共享该位置包含的认证/更新令牌 。 这是通过OS认证商店完成的. 由你来实施 `ICredentialStore` 并将其纳入您的选项 `AzCopyClient` 如果你愿意的话.

```js
new AzCopyClient({
    credentialStore: {
        setEntry: async (service: string, account: string, value: string, exePath?: string, description?: string): Promise<void> => {
            // you implement this
        },
        getEntry: async (service: string, account: string): Promise<string | null> => {
            // you implement this
        },
        deleteEntry: async (service: string, account: string): Promise<boolean> => {
            // you implement this
        }
    }
});
```

更多信息见JSDoc的评论 `ICredentialStore` 财务报告和审定财务报表 `TokenRefresher`。 。 。 .

## 常规

在macOS和Linux上你可能需要 `chmod` 执行文件,以便它们运行.

## 更改日志

### 3.4.15 (中文(简体) )

-   与AzCopy 10.32.2作对.

### 3.4.14 联合国

-   校对:AzCopy 10.320.

### 3.4.13 联合国

-   对AzCopy的验证103.1.1.

### 3.4.12 (中文(简体) )

-   与AzCopy 10.310.
-   已添加 `preserveSymlinks` 改为 `ICopyOptions` 用于NFS转让.

### 3.4.11 联合国

-   与AzCopy 10.30.1作对.

### 3.4.10 (中文(简体) )

-   _突破变革!_ 已重命名 `preserveSmbInfo` 改为 `preserveInfo` 财务报告和审定财务报表 `preserveSmbPermissions` 改为 `preservePermissions` 内 `ICopyOptions` 反映通用的 AzCopy 旗帜(`--preserve-info`, (中文(简体) ), `--preserve-permissions`) (中文(简体) ).
-   已添加 `"File"` 改为 `AzCopyTarget` 用作通用文件共享目标 `"FileSMB"` 财务报告和审定财务报表 `"FileNFS"`。 。 。 .
-   `getFromToOption()` 现在返回无效组合的等效有效选项(例如, `getFromToOption("Blob", "FileSMB")` 返回时 `"BlobFile"`) (中文(简体) ).

### 3.4.9 (中文(简体) )

-   对AzCopy10.0.
-   新增 NFS 文件共享支持 `"FileNFS"` 财务报告和审定财务报表 `"FileSMB"` 目标 `AzCopyTarget`。 。 。 .
-   已更改 `FromToOption` 从硬编码结合到计算类型 `AzCopyTarget` 组合.
-   已添加 `getFromToOption()` 计算有效的助手函数 `--from-to` 源/目的地目标选项.

### 3.4.8 (中文(简体) )

-   当在Node.js Windows ARM64上运行时, `AzCopyClient` 现在使用/优先使用 `@azure-tools/azcopy-win-arm64` 过 `@azure-tools/azcopy-win64` 伊丝.

### 3.4.7 (中文(简体) )

-   对AzCopy 10.29.1进行了验证.
-   被移动到使用SHA256与AzCopy共享符.

### 3.4.2 国家

-   校对:AzCopy 10.26.0.

### 3.4.1 国家

-   对AzCopy 10.25.1进行了验证.

### 3.3.0 (单位:千美元)

-   校对:AzCopy 10.24.0.
-   设置了 HTTPS PROXY 或 NO PROXY 环境变量后, AzCopy 客户端无法启动任务 .
-   当在Node.js Windows ARM64上运行时, `AzCopyClient` 现在使用/优先使用 `@azure-tools/azcopy-win64` 过 `@azure-tools/azcopy-win32` 伊丝.

### 3.2.0 (中文(简体) )

-   对AzCopy 10.23.0.

### 3.1.0 (中文(简体) )

-   与AzCopy 10.2.2作对.
-   已添加 `getCliCommand` 方法打开 `AzCopyClient`。 。 。 .

### 3.0.0 (单位:千美元)

-   添加了macOS ARM64 AzCopy作为依赖.
-   已添加 `trailingDot` 改为 `ICommonOptions`。 。 。 .
-   删除 `Bitness` 从 `IAzCopyClientOptions`。 。 。 .
-   更新了获取 AzCopy 可执行文件的功能 .

### 2.1.20. 国家

-   对AzCopy的验证
-   添加“ 粗体” 作为支持的块 blob 级 `ICopyOptions`。 。 。 .

### 2.11.0. 国家

-   对AzCopy进行验证
-   改进评论 `listOfFiles` 财务报告和审定财务报表 `listOfVersions` 内 `ICommonOptions`。 。 。 .

### 2.10.1 国家

-   已添加 `"FileBlob"` 财务报告和审定财务报表 `"BlobFile"` 改为 `FromToOption`

### 2.1.0 国家

-   已添加 `preserveBlobTags` 改为 `ICopyOptions`

### 2.9.0 国家

-   已添加 `jobsRemove` 方法打开 `AzCopyClient`

### 2.8.0 (中文(简体) )

-   对AzCopy的验证
-   已添加 `"FileFile` 改为 `FromToOption`
-   已添加 `includeRegex` 改为 `ICopyOptions`
-   已添加 `asSubDir` 改为 `ICopyOptions`
-   为了方便,增加了几个新类型:
    -   `OverwriteExistingOption` 用于: `ICopyOptions`
    -   `AccessTier` 用于: `ICopyOptions`
    -   `RemoteAzCopyLocation` 所有偏远地区的结合

### 2.7.0 (中文(简体) )

-   对AzCopy进行验证 10.16.0
-   添加a `deleteJob` 方法 `AzCopyClient`。当任务的信息/状态不再需要时,使用此函数保存内存.
-   添加对动态改变带宽的支持 。 支助包括:
    -   增 编 `nextPerformanceAdjustmentTime` 改为 `IJobInfo`
    -   增 编 `adjustCapMbps` 方法打开 `AzCopyClient`

### 2.6.0 (中文(简体) )

-   与AzCopy 10.14.1作对.

### 2.5.0 (中文(简体) )

-   校对:AzCopy 10.13.0.

### 2.4.0 (中文(简体) )

-   对AzCopy的鉴定
-   已添加 `includeDirectoryStub` 改为 `ICopyOptions`
-   固定 `--trusted-microsoft-suffixes` 正在添加到命令时 `trustedDomainSuffixes` 是一空数组.

### 2.3.0 (单位:千美元)

-   对AzCopy的验证
-   两者共同的选项 `ICopyOptions` 财务报告和审定财务报表 `IDeleteOptions` 被移动到一个新的界面, `ICommonOptions`,与 `ICopyOptions` 财务报告和审定财务报表 `IDeleteOptions` 每一个都继承了这个接口.
-   已添加 `includePath` 改为 `ICopyOptions` 财务报告和审定财务报表 `IDeleteOptions`。 。 。 .
-   已添加 `logLevel` 改为 `ICopyOptions` 财务报告和审定财务报表 `IDeleteOptions`。 。 。 .
-   已添加 `disableAutoDecoding` 改为 `ICopyOptions`。 。 。 .
-   已添加 `cacheControl` 改为 `ICopyOptions`。 。 。 .

### 2.2.0 (中文(简体) )

-   对AzCopy 10.10.
-   已添加 `blockSizeMb` 改为 `ICopyOptions`。 。 。 .
-   已添加 `trustedDomainSuffixes` 改为 `ICopyOptions` 财务报告和审定财务报表 `IDeleteOptions`。 。 。 .

### 2.1.0 国家

-   校对:AzCopy 10.9.0.

### 2.0.0 (韩语)

-   校对:AzCopy 10.8.0.
-   _突破变革!_ 此套件不再直接依赖于 `keytar` 或者说 `macos-keychain`。如果想要使用 `IRemoteAuthLocation` 您现在必须执行 `ICredentialStore` 并将其纳入您的选项 `AzCopyClient`。见 [Azure AD 设想方案](https://npmcn.com/package/%40azure-tools/azcopy-node/#readme-azure-ad-scenarios) 和联合来文文件的评论 `ICredentialStore` 财务报告和审定财务报表 `TokenRefresher` 更多信息.
-   现在所有远程地点都包含一个可选位置 `versionId`。这可用于指向blob版本.
-   已添加 `listOfVersions` 改为 `ICopyOptions` 财务报告和审定财务报表 `IDeleteOptions`类似工作 `listOfFiles`。详见两个选项文件中的JSDoc评论.
-   已添加 `"Archive"` 作为可能值 `accessTier` 复制选项.
-   已添加 `forceIfReadOnly` 改为 `IDeleteOptions`。 。 。 .
-   已添加 `tags` 改为 `ICopyOptions`。 。 。 .

### 1.0.0 (单位:千美元)

-   这个包的第一个版本!
-   校对:AzCopy 10.5.0.

## 常见问题

### @azure-tools/azcopy-node 是什么？

此软件包允许您引用 AzCopy v 10 \(英语\) 从NodeJS\.

### 如何安装 @azure-tools/azcopy-node？

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

### @azure-tools/azcopy-node 支持 TypeScript 吗？

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

### @azure-tools/azcopy-node 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @azure-tools/azcopy-node 可以商用吗？

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

### @azure-tools/azcopy-node 的下载量有多少？

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

### @azure-tools/azcopy-node 还在维护吗？

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