# @buttercup/dropbox-client 中文文档

规范地址：https://npmcn.com/package/%40buttercup/dropbox-client/

版本：2\.2\.0
npm 元数据更新时间：2023-11-11T05:34:01.041Z
中文译文更新时间：2026-11-08T20:36:21.662Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：24.6 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2018-11-15T20:33:57.638Z
- 最新版本发布：2023-11-11T05:34:00.811Z
- 近 30 天下载量：2409（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 0 个）

## 中文简介

Dropbox 客户端库

## 安装

```sh
npm install @buttercup/dropbox-client
```

也可以使用：`pnpm add @buttercup/dropbox-client`、`yarn add @buttercup/dropbox-client`、`bun add @buttercup/dropbox-client`

## README

# 丢弃框客户端

> Buttercup 的 Dropbox 客户端库

[![Buttercup](https://cdn.rawgit.com/buttercup-pw/buttercup-assets/6582a033/badge/buttercup-slim.svg)](https://buttercup.pw/) [![npm version](https://badge.fury.io/js/%40buttercup%2Fdropbox-client.svg)](https://www.npmjs.com/package/@buttercup/dropbox-client) ![Tests status](https://github.com/buttercup/dropbox-client/actions/workflows/test.yml/badge.svg)

## 关于

Dropbox是Buttercup平台的一个组成部分,因为它被大量用户用来存储各种数据——包括Buttercup金库文件. 拥有实用,可移植和可靠的Dropbox客户端接口对于平台的稳定性至关重要,目前官方的Dropbox SDK在质量和稳定性方面都缺乏.

这个库是一个赤骨 HTTP 客户端,可以直接向 Dropbox 的 HTTP API 发送请求,使用一个符号( 外部处理 - 这个库将不负责获取它们) 。 结果是一个小而可移植的脚本,可靠而简单易懂. 用这个 `fetch` (单位:千美元)[横切](https://github.com/lquixada/cross-fetch))执行请求,这显然将在可复制的跨环境快活中发挥作用.

## 安装

随便跑 `npm install @buttercup/dropbox-client --save` 要安装.

最新版本(v2)要求 [无害环境管理](https://nodejs.org/api/esm.html) 要运行的环境 。 标准CommonJS项目无法使用.

## 使用量

### 授权

您可以使用 Dropbox 授权 URL 生成 `generateAuthorisationURL`数字 :

```typescript
import { generateAuthorisationURL } from "@buttercup/dropbox-client";

const url = generateAuthorisationURL("client-id", "https://redir.example.com");
// open `url`
```

### 客户端

使用 `DropboxClient` 创建客户端界面的类 :

```typescript
import { generateAuthorisationURL } from "@buttercup/dropbox-client";

const client = new DropboxClient("my-token");
```

然后,你可以使用 `client` 用于请求目录内容的适配器 :

```typescript
client
    .getDirectoryContents("/Documents")
    .then(contents => {
        // [ {
        //     name: "My directory",
        //     path: "/Documents/My directory",
        //     type: "directory"
        // }, {
        //     name: "results.pdf",
        //     path: "/Documents/results.pdf",
        //     type: "file"
        // } ]
    });
```

您也可以使用 `getFileContents` 财务报告和审定财务报表 `putFileContents`分别是:.

### 兼容模式

您可以为基于浏览器的环境启用兼容模式, CORS 可以中断请求 :

```typescript
const client = new DropboxClient("my-token", { compat: true });
```

在一些浏览器环境中,“ CORS hack” Content-Type 头头可能失败, 因此可以通过指定来禁用 `false` 联 合 国 `compatCorsHack` 属性 :

```typescript
const client = new DropboxClient("my-token", {
    compat: true,
    compatCorsHack: false
});
```

### 自定义信头

您可以为客户端的所有请求提供自定义信头,具体方式是指定 `headers` 选项 :

```typescript
const client = new DropboxClient("my-token", {
    headers: {
        // Disable the cache (works/necessary in some environments)
        "Cache-Control": "no-cache, no-store, max-age=0"
    }
});
```

### Fs 数

一个 `fs`\- 类似接口也可用 :

```typescript
import { generateAuthorisationURL } from "@buttercup/dropbox-client";

const client = new DropboxClient("my-token");

client.fs.readdir("/photos", (err, items) => {
    // array of file names
});
```

### 处理错误

执行针对 Dropbox API 的请求时出错将丢入包 [`Layerr`](https://github.com/perry-mitchell/layerr) 错误实例 。 它为每个错误提供了一些额外的属性:

```typescript
import { Layerr } from "layerr";

// ...

client.getDirectoryContents("/").catch((err) => {
    const {
        status,
        statusText,
        url
    } = Layerr.info(err);

    if (status === 403) {
        // ...
    }
});
```

## 常见问题

### @buttercup/dropbox-client 是什么？

Dropbox 客户端库

### 如何安装 @buttercup/dropbox-client？

在项目目录运行 npm install @buttercup/dropbox-client，或使用 pnpm add / yarn add / bun add。

### @buttercup/dropbox-client 支持 TypeScript 吗？

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

### @buttercup/dropbox-client 支持 ESM 还是 CommonJS？

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

### @buttercup/dropbox-client 可以商用吗？

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

### @buttercup/dropbox-client 的下载量有多少？

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

### @buttercup/dropbox-client 还在维护吗？

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