# cesiumcloud 中文文档

规范地址：https://npmcn.com/package/cesiumcloud/

版本：0\.2\.41
npm 元数据更新时间：2026-11-03T07:12:26.237Z
中文译文更新时间：2026-11-03T07:31:24.833Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/cesiumcloud
原文对照：https://npmcn.com/package/cesiumcloud/?lang=original
项目主页：https://github.com/v12-enginee/cesiumcloud-clients-release#readme
源码仓库：https://github.com/v12-enginee/cesiumcloud-clients-release

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

- 包体积（解压后）：142 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-10-27T02:30:28.365Z
- 最新版本发布：2026-11-03T07:12:26.093Z
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

CesiumCloud命令行客户端和SDK用于云文件管理

## 安装

```sh
npm install cesiumcloud
```

也可以使用：`pnpm add cesiumcloud`、`yarn add cesiumcloud`、`bun add cesiumcloud`

## README

# CesiumCloud - Node.js CLI和SDK

**版本0.2.41·Node.js 22+·Windows， macOS和Linux**

从终端或从Node.js管理云文件和文件夹。支持上传、下载、导航、列表、搜索、移动、重命名、删除和可选的本地加密文件。

Web应用程序: [https://cloud.cesiummc.space/app/](https://cloud.cesiummc.space/app/) ·npm: [https://www.npmjs.com/package/cesiumcloud](https://www.npmjs.com/package/cesiumcloud) · [完整的参考](https://github.com/v12-enginee/cesiumcloud-clients-release/blob/main/docs/CLI_REFERENCE.md)

## 安装并登录

```bash
npm install -g cesiumcloud@0.2.41
cesiumcloud --version
cesiumcloud authenticate
cesiumcloud whoami
```

遵循浏览器/设备授权说明。本地保存的凭据用于后续命令。您不需要将令牌粘贴到终端命令中。

在Windows PowerShell或CMD中使用 `npm.cmd` 和 `cesiumcloud.cmd` 如果shell命令解析需要它们。始终引用包含空格、特殊字符或括号的完整Windows路径。

```powershell
npm.cmd install -g cesiumcloud@0.2.41
cesiumcloud.cmd authenticate
cesiumcloud.cmd upload "E:\Downloads\My project (1).zip"
```

`cesiumcloud upgrade` (或 `update`)从官方的NPM注册表安装当前版本。 `cesiumcloud logout` 删除保存的本地凭据；通过您的CesiumCloud帐户单独撤销设备。

## 命令参考

| 命令 | 目的 |
| --- | --- |
| `authenticate` / `whoami` / `logout` | 授权、检查或移除本地授权 |
| `upgrade` / `update` / `--version` | 升级或检查已安装的命令行 |
| `stats` | 显示当前帐户的容量和使用情况 |
| `upload SOURCE [and SOURCE...]` | 上传本地文件和/或目录 |
| `upload --replace SOURCE` | 替换同一云路径上的现有文件 |
| `upload cancel` | 从另一个终端取消这台计算机的活动CLI上传 |
| `uploads` | 检查未完成的传输和未完成的清理 |
| `cancel-upload UPLOAD_ID` | 按会话标识符取消未完成的上传 |
| `resume-upload UPLOAD_ID LOCAL_FILE` | 遗留兼容性命令；正常取消的上传被删除 |
| `discard-upload UPLOAD_ID` | 显式放弃不完整的传输 |
| `download CLOUDPATH [and CLOUDPATH...]` | 下载命名文件或云文件夹 |
| `download --all LOCALDIR` | 在LOCALDIR下恢复帐户的文件 |
| `download cancel` | 取消这台计算机的活动CLI下载 |
| `list` / `search TERM` / `dir` | 浏览并更改当前云目录 |
| `rename OLD NEW` / `move SOURCE [to] DEST` | 重命名或移动云项 |
| `delete CLOUDPATH` | 将选定的云文件移至回收站，可恢复48小时 |
| `e2ee help` | 请参阅可选的客户端加密命令 |

你可以跑 `cesiumcloud help COMMAND` 或者 `cesiumcloud COMMAND --help` 获取特定于命令的帮助。 `[and]` 和 `[to]` 是文字分隔符，而不是文件名。对于多源命令，请引用 _每一个_ 路径分别。

### 上传文件和目录

```bash
cesiumcloud upload "./backup.zip"
cesiumcloud upload "./Projects"
cesiumcloud upload "./backup.zip" --replace
cesiumcloud upload "./a.zip" [and] "./b.zip" -simultaneous 2
cesiumcloud upload "./My Folder" -simultaneous 20
```

单文件上传使用下面描述的标准配置。上传目录时，保留其嵌套路径和空文件夹。多个源和目录上传运行独立的文件传输，最多可达 **40个活动文件上传** 默认情况下，对于目录； `-simultaneous N` 或者 `--simultaneous N` 控制并发性（可接受的N: 1-64；活动上传限制40）。当容量可用时，允许上传。现有的云路径要求 `--replace`.

### 下载文件，目录和整个帐户

```bash
cesiumcloud download "archive.zip"
cesiumcloud download "archive.zip" --location "./Restored"
cesiumcloud download "photos" --location "./Restored"
cesiumcloud download "first.zip" [and] "second.zip" --location "./Restored" -simultaneous 2
cesiumcloud download --all "./RestoredAccount" -simultaneous 8
```

没有 `--location`，命名下载使用操作系统下载目录，不一定是当前终端目录。通过选择一个编号的备选项来保留现有的本地文件名。下载文件夹时，将在所选目标下创建文件夹，并使用其嵌套结构和空文件夹。 `--all` 还原所选本地目录下面的帐户层次结构。下载并发是1 - 64（默认：1）。

### 浏览，组织和删除

```bash
cesiumcloud dir /
cesiumcloud dir "photos"
cesiumcloud dir ..
cesiumcloud list
cesiumcloud list -a
cesiumcloud list -n 20 -sort name
cesiumcloud list -next 15
cesiumcloud list -sort datecreated -long
cesiumcloud search ext:png
cesiumcloud search "holiday" [and] "2026"
cesiumcloud rename "old.txt" "new.txt"
cesiumcloud rename "old.txt" "newname" -ne
cesiumcloud move "a.txt" [and] "b.txt" [to] "archive"
cesiumcloud delete "archive/a.txt"
```

`dir` 不带参数显示当前云目录； `dir /` 返回到root帐户。 `list` 默认为按大小排序的前15个文件； `-a` 递归地列出, `-n N` (或 `N` / `-N`)控制计数； `-next N` 移动已保存的光标， `-sort` 需要 `size`， `name`， `datecreated`， `lastmodified` 或者 `reset`； `-long` 显示的元数据。 `search` 使用不区分大小写的路径匹配； `ext:png` 匹配扩展。 `rename` 当新名称没有扩展名时，保留现有文件的扩展名，除非 `-ne` 提供。 `delete` 是永久的。

## 取消转移

**自从0.2.41**， Ctrl+C报告永久取消完成后，远程上传会话和它的保留已被删除；如果无法确认删除，它会显式报告待处理的清理 在将远程删除和队列清理处理给分离的进程后立即执行。 这个消息意味着清理是 **在进步**，而不是服务器删除 已经确认了。检查 `cesiumcloud uploads` 如果需要的话。

-   在Node.js CLI传输过程中， **Ctrl + C** 请求取消。v0.2.29增加了Windows Ctrl+C和Ctrl+Break控制台处理；仍然支持正常的Unix SIGINT行为。如果选择文本时终端将Ctrl+C视为复制，则清除所选内容。
-   从一个 **同一台计算机上的第二个终端**,使用 `cesiumcloud upload cancel` 或者 `cesiumcloud download cancel`． 当控制台中断键被截获时，这些命令也可以工作。它们仅影响相同CesiumCloud CLI配置中的作业，而不影响其他设备或网站上的作业。
-   `cesiumcloud cancel-upload UPLOAD_ID` 可以取消特定的未完成的服务器上传。使用 `cesiumcloud uploads` 检查需要清理的条目。
-   上传被取消或失败 **不保存以备以后恢复**． 它未完成的服务器数据被删除；已经完成的云文件将被保存。如果服务器正在确认清除，则取消可能需要更长的时间。强制终止的进程可能需要自动恢复和清理。
-   取消下载将删除不完整的临时本地文件；已经完成的下载仍然存在。取消下载不会删除远程文件。

## 上传设置

**单个文件（Node.js）的默认值：** 99,876,864字节的块（100,000,000字节下最大的256 kb对齐大小），1 MiB HTTP流块和一个块预读。不需要任何环境变量。这些默认值是从实际传输测量中选择的；吞吐量取决于您的连接和存储容量。

| 变量 | 接受的价值观 | 行为 |
| --- | --- | --- |
| `CESIUMCLOUD_UPLOAD_CHUNK_MB` | `100` | 显式接近100 MB的块；覆盖MiB变量 |
| `CESIUMCLOUD_UPLOAD_CHUNK_MIB` | `64` 或者 `95` | 可选的较小块；最大为100mb |
| `CESIUMCLOUD_UPLOAD_PREFETCH` | `0` 或者 `1` | `1` 是默认值； `0` 禁用下一个块预读 |
| `CESIUMCLOUD_UPLOAD_STREAM_BLOCK_KIB` | `256`， `1024` 或者 `4096` | 内部流块；默认的 `1024` (1 MiB) |
| `CESIUMCLOUD_CONFIG_DIR` | 目录路径 | 使用备用本地授权/配置目录 |
| `CESIUMCLOUD_API_KEY` | 现有有效设备令牌 | 可选的编程/自动化证书；永远不要分享 |

预读可能会使用大约100 MB的额外内存块。并发文件夹上传使用较小的每个文件块来控制内存使用。

**PowerShell:**

```powershell
$env:CESIUMCLOUD_UPLOAD_PREFETCH = "0"
cesiumcloud.cmd upload "E:\Backups\archive.zip"
Remove-Item Env:\CESIUMCLOUD_UPLOAD_PREFETCH
```

**Bash:**

```bash
CESIUMCLOUD_UPLOAD_PREFETCH=0 cesiumcloud upload "./archive.zip"
```

文件夹/批传输使用单独的文件上传路径，不等同于单个大文件传输。

## JavaScript SDK

包导出 `IsolatedTransferClient` 用于文件管理和 `CesiumCloudClient` 用于高级设备授权和cli支持的操作。在Node.js 22+中：

```js
const { IsolatedTransferClient } = require("cesiumcloud");
const client = new IsolatedTransferClient(process.env.CESIUMCLOUD_API_KEY);
async function example() {
  await client.uploadFile("./notes.txt", "docs/notes.txt");
  const files = await client.allFiles();
  const doc = files.find(file => file.path === "docs/notes.txt");
  if (doc) await client.download(doc.id, "./notes-restored.txt");
}
example().catch(console.error);
```

SDK操作需要一个有效的授权令牌。底层客户端支持 `uploadFile`， `uploadPath`， `download`， `downloadPath`， `list`， `allFiles`， `byPath`， `delete`， `rename`， `renameFolder`， `mkdir`， `rmdir`， `directoryExists`， `pendingUploads`， `cancelUpload` 和更多;看到 [SDK参考](https://github.com/v12-enginee/cesiumcloud-clients-release/blob/main/docs/SDK_REFERENCE.md)． 默认情况下，SDK下载拒绝现有目标，除非显式启用覆盖，这与选择编号文件名的CLI下载不同。

## 可选端到端加密

```bash
cesiumcloud e2ee keygen
cesiumcloud e2ee encrypt "./notes.txt" --location "./Encrypted"
cesiumcloud e2ee decrypt "./Encrypted/notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee upload "./notes.txt"
cesiumcloud e2ee download "notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee migrate "old.txt"
```

`keygen` 创建本地存储的恢复密钥。 **离线备份，永远不要泄露。** 正常的 `upload` 仍是未加密的。加密的 `.ccenc` 格式保护内容，而不是路径、文件名、大小或活动元数据。 `e2ee migrate` 创建并验证加密副本，同时默认保留原始副本；原要求移除 _两个_ `--purge-original` 和 `--i-backed-up-key`． 在没有保留可用恢复键的情况下，不要设置清除标志。

## 故障排除和兼容性

| 症状 | 行动 |
| --- | --- |
| `cesiumcloud` 在PowerShell中无法识别 | 运行 `cesiumcloud.cmd` 或者重新安装全局NPM包并打开一个新的终端 |
| Ctrl+C在Windows上无效 | 升级到0.2.29+，清除选定的文本，或使用 `cesiumcloud.cmd upload cancel` 从另一个终端 |
| 上传路径未找到 | 报价的 **整个** 本地文件名，包括括号 |
| 文件已远程存在 | 添加 `--replace` 只有当你想换新的时候 |
| 下载文件名已存在 | CLI选择一个编号的替代；SDK需要明确的覆盖决策 |
| 上传在传输中停止 | 运行 `cesiumcloud uploads` 检查清理工作；正常取消的上传不能恢复 |
| 错误413，容量限制或长队列 | 使用标准块默认值，减少并发传输或在帐户容量允许时重试 |
| 不能解密 `.ccenc` 文件 | 还原准确备份的恢复密钥；仅重新身份验证无法解密它 |

寻求帮助 `cesiumcloud --help` 和 `cesiumcloud e2ee help`． 有关命令示例、环境变量和历史更改，请参阅源代码发行版附带的文档。

**安全:** CLI删除使用可恢复的48小时Trash；明确的SDK删除是永久性的，上传替换可以改变现有内容。保留重要文件和加密密钥的独立备份。

### Windows版本和软件包升级

使用 `where cesiumcloud` 来检查哪个可执行Windows启动。Python的脚本可执行文件可能位于npm CLI的PATH上。使用 `cesiumcloud.cmd version` 对于NPM全局客户端或 `python -m cesiumcloud version` Python。这个 `upgrade` 和 `update` 当两个包都安装时，命令会更新这两个包类型。对于npm全局安装使用 `npm install -g cesiumcloud`； 没有 `-g` NPM安装到当前项目中。

在传输字节之前，通过队列允许上传。该服务强制允许，以防止通过直接请求跳过队列。上传块的大小上限为100 MB。

### 在0.2.41中删除文件夹

使用带有引号的云文件夹路径的delete命令。它将该目录及其所有内容移动到48小时可恢复的垃圾桶中，包括空文件夹；它从不调用永久删除。支持后面的Windows反斜杠。

## 常见问题

### cesiumcloud 是什么？

CesiumCloud命令行客户端和SDK用于云文件管理

### 如何安装 cesiumcloud？

在项目目录运行 npm install cesiumcloud，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cesiumcloud，可以用 npx cesiumcloud 直接运行。

### cesiumcloud 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cesiumcloud 是否存在。

### cesiumcloud 支持 ESM 还是 CommonJS？

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

### cesiumcloud 需要什么版本的 Node\.js？

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

### cesiumcloud 可以商用吗？

cesiumcloud 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### cesiumcloud 还在维护吗？

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