@fastcar/cossdk

FastCar COS SDK 封装，用于访问 FastCar COS 服务端提供的文件上传、下载、目录管理、权限管理、重定向、账号管理和图片处理接口。

安装

npm install @fastcar/cossdk

或：

yarn add @fastcar/cossdk

快速开始

import { COSSDK, getSign } from "@fastcar/cossdk";

const account = {
	appid: "your-appid",
	// 字段名沿用服务端账号字段：serectkey
	serectkey: "your-32-byte-secret-key-value",
};

// getSign 依赖 Node.js crypto，建议只在服务端生成签名。
const sign = getSign(
	{
		appid: account.appid,
		expireTime: Math.floor((Date.now() + 5 * 60 * 1000) / 1000),
		dir_path: "/",
		mode: 7,
	},
	account.serectkey
);

if (!sign) {
	throw new Error("生成 COS 签名失败");
}

const cosSDK = new COSSDK({
	domain: "https://cos.example.com",
	sign,
});

浏览器端不建议保存 serectkey 或调用 getSign。推荐由业务服务端生成短有效期签名后下发给前端使用。

签名说明

getSign(signInfo, serectkey) 用于生成访问签名，仅支持 Node.js 服务端环境。

type SignType = {
	appid: string;
	expireTime: number;
	dir_path: string;
	mode: number;
};

| 字段 | 说明 | | --- | --- | | appid | COS 账号 ID | | expireTime | 过期时间，Unix 秒级时间戳 | | dir_path | 授权访问路径，例如 /、/images | | mode | 权限位，1 可读，2 可写，4 可查，可相加组合 |

常用 mode：

| 值 | 权限 | | --- | --- | | 1 | 只读 | | 2 | 只写 | | 3 | 读写 | | 4 | 只查询 | | 7 | 读、写、查询 |

如果签名过期或需要切换账号，可使用 setSign 更新：

cosSDK.setSign(newSign);

也可以通过 COS 服务端接口创建签名：

const result = await cosSDK.createSign({
	appid: "your-appid",
	serectkey: "your-32-byte-secret-key-value",
	expireTime: Math.floor((Date.now() + 10 * 60 * 1000) / 1000),
	dir_path: "/uploads",
	mode: 7,
});

console.log(result.data);

文件操作

上传文件

const blob = new Blob(["hello world"], { type: "text/plain" });
const file = new File([blob], "hello.txt");

const result = await cosSDK.uploadfile("/docs/hello.txt", file);

console.log(result.data.data);

uploadfile(filename, file) 会使用 multipart/form-data 上传文件，filename 是目标存储路径。

下载文件

const response = await cosSDK.getFile("/docs/hello.txt");

console.log(response.data);

私有文件可传入 auth: true，SDK 会附带当前签名：

const response = await cosSDK.getFile("/private/report.pdf", true);

console.log(response.headers["content-type"]);

如果 filename 是 http 开头的完整 URL，SDK 会直接请求该 URL。

查询文件列表

const result = await cosSDK.queryFilelist("/docs");

for (const item of result.data ?? []) {
	console.log(item.name, item.file, item.size);
}

返回项字段：

| 字段 | 说明 | | --- | --- | | name | 文件或目录名称 | | create_time | 创建时间 | | modify_time | 修改时间 | | size | 文件大小 | | file | 是否为文件 |

创建目录

await cosSDK.createDir("/docs", "private");

permission 可选值为 public 或 private。

删除文件

const ok = await cosSDK.deleteFile("/docs/hello.txt");
console.log(ok);

删除分块文件：

const ok = await cosSDK.deleteChunkFile("/chunks/video.mp4", 12);
console.log(ok);

重命名文件或目录

const ok = await cosSDK.rename("/docs/old.txt", "/docs/new.txt");
console.log(ok);

解压文件

await cosSDK.extractFile("/packages/demo.zip", "/packages/demo");

权限管理

设置文件或目录权限：

await cosSDK.setPermissions({
	filename: "/docs/hello.txt",
	permission: "public",
});

查询权限：

const permission = await cosSDK.getPermissions({
	filename: "/docs/hello.txt",
});

console.log(permission.permission, permission.source);

删除显式权限配置：

await cosSDK.delPermissions({
	filename: "/docs/hello.txt",
});

source 为 set 表示当前路径显式设置了权限，为 extend 表示继承上级目录权限。

账号管理

初始化当前服务账号：

const account = await cosSDK.initAccount();
console.log(account.data.appid, account.data.serectkey);

生成账号信息：

const account = await cosSDK.genAccountInfo();
console.log(account.data);

添加账号：

const account = await cosSDK.addAccount();
console.log(account.data);

删除账号：

await cosSDK.delAccount("target-account-id");

查询账号列表：

const accounts = await cosSDK.getAccountList();
console.log(accounts);

校验当前签名：

const code = await cosSDK.checkSign();
console.log(code);

重定向与域名

设置重定向：

await cosSDK.setRedirect({
	redirectUrl: "/docs/index.html",
	flag: false,
	bucket: "docs",
});

查询全部重定向配置：

const result = await cosSDK.getRedirect();
console.log(result.data.redirect, result.data.defaultredirect);

查询单个重定向：

const result = await cosSDK.queryRedirect({
	bucketUrl: "/docs",
});

console.log(result.data);

删除重定向配置：

await cosSDK.delRedirect({
	bucket: "docs",
});

获取域名列表：

const result = await cosSDK.getDomains();
console.log(result.data);

保存域名列表：

await cosSDK.saveDomains(["https://cdn.example.com"]);

图片处理

服务端 COS 模板提供 /image/generatePreview 和 /image/resize 接口。filename 和 sourceUrl 必须二选一，targetFilename 必填，输出新文件且不会覆盖源文件或已有目标文件。

生成预览图

const result = await cosSDK.generatePreview({
	filename: "/images/demo.png",
	targetFilename: "/images/demo-preview.webp",
});

console.log(result.data.previewUrl);

处理外部 URL：

const result = await cosSDK.generatePreview({
	sourceUrl: "https://example.com/demo.png",
	targetFilename: "/images/external-preview.webp",
});

console.log(result.data.previewWidth, result.data.previewHeight);

可按单次请求覆盖服务端默认阈值：

const result = await cosSDK.generatePreview({
	filename: "/images/demo.png",
	targetFilename: "/images/demo-preview.webp",
	maxLongEdge: 640,
	webpQuality: 76,
	maxDimension: 8192,
	localImageMaxBytes: 100 * 1024 * 1024,
});

console.log(result.data.previewSizeBytes);

等比缩放

const result = await cosSDK.resizeImage({
	filename: "/images/demo.png",
	targetFilename: "/images/demo-640.png",
	width: 640,
});

console.log(result.data.resultUrl, result.data.upscaled);

也可以指定高度：

const result = await cosSDK.resizeImage({
	filename: "/images/demo.png",
	targetFilename: "/images/demo-360.png",
	height: 360,
});

console.log(result.data.resultWidth, result.data.resultHeight);

resizeImage 输出格式保持源图片格式。例如源图是 PNG，则输出内容仍是 PNG。

通用请求

当服务端新增接口但 SDK 暂未封装时，可使用 request 发送带签名的请求：

type ResponseData = {
	code: number;
	data: string[];
};

const result = await cosSDK.request<{ prefix: string }, ResponseData>({
	url: "/custom/list",
	method: "GET",
	data: {
		prefix: "/docs",
	},
});

console.log(result?.data);

GET 请求会把 data 和 sign 放入 query 参数；非 GET 请求会自动携带 sign 参数，data 作为请求体发送。

API 列表

| 方法 | 说明 | | --- | --- | | new COSSDK({ domain, sign }) | 创建 SDK 实例 | | setSign(sign) | 更新当前签名 | | createSign(params) | 通过服务端接口创建签名 | | initAccount() | 初始化账号 | | genAccountInfo() | 生成账号信息 | | addAccount() | 添加账号 | | delAccount(account) | 删除账号 | | getAccountList() | 获取账号列表 | | checkSign() | 校验当前签名 | | uploadfile(filename, file) | 上传文件 | | getFile(filename, auth?) | 下载或访问文件 | | queryFilelist(filename) | 查询文件列表 | | createDir(dirname, permission?) | 创建目录 | | deleteFile(filename) | 删除文件 | | deleteChunkFile(filename, totalChunks) | 删除分块文件 | | rename(filename, newFilename) | 重命名文件或目录 | | extractFile(filename, targetDir) | 解压文件 | | setPermissions(params) | 设置权限 | | getPermissions(params) | 查询权限 | | delPermissions(params) | 删除权限配置 | | setRedirect(params) | 设置重定向 | | getRedirect() | 查询全部重定向配置 | | queryRedirect(params) | 查询单个重定向 | | delRedirect(params) | 删除重定向配置 | | getDomains() | 获取域名列表 | | saveDomains(domains) | 保存域名列表 | | generatePreview(params) | 生成图片预览图 | | resizeImage(params) | 等比缩放图片 | | request(params) | 发送自定义请求 |

注意事项

• domain 传入时可以带尾部 /，SDK 会自动去除。
• 文件路径建议统一使用 / 开头；部分方法会自动补齐，部分方法会按原值传给服务端。
• getSign 依赖 Node.js crypto，不要在浏览器端暴露 serectkey。
• serectkey 是当前服务端字段名，虽然拼写不是 secretkey，使用时仍需保持一致。
• 图片处理依赖服务端模板能力，客户端只负责调用接口。

项目开源地址

• 项目下载：git clone https://github.com/williamDazhangyu/fast-car.git
• 在线查看：https://github.com/williamDazhangyu/fast-car