Classic Cloud Storage
In classic mode, CloudBase JS SDK v3 provides cloud storage file operations through app.storage.from(). Classic mode works with the built-in cloud storage of an environment. Upload APIs take storage-relative paths and return full fileIDs. For download, deletion, signed URLs, and file metadata queries, use the full fileID returned by upload.
In classic mode, storage APIs use the open capabilities of the Cloud Storage HTTP API. Before using them, check whether the StoragesHttpApiAllow policy is configured as expected. See Policy Management for details.
Quick Start
import cloudbase from "@cloudbase/js-sdk";
const app = cloudbase.init({ env: "your-env-id" });
const storage = app.storage.from();
const { data, error } = await storage.upload("images/photo.jpg", file);
if (error) throw error;
const fileID = data.id;
const { data: blob } = await storage.download(fileID);
const { data: signed } = await storage.createSignedUrl(fileID, 3600);
await storage.remove([fileID]);
API Methods
Client Entry
- from() - Get the classic cloud storage file operation client
- throwOnError() - Throw on error
File Operations
- upload() - Upload files
- update() - Update files
- download() - Download files
- remove() - Delete files
- move() - Move files
- copy() - Copy files
URL Management
- createSignedUrl() - Create a signed URL
- createSignedUrls() - Create signed URLs in batch
- getPublicUrl() - Get a public URL
- createSignedUploadUrl() - Create a signed upload URL
File Information
from
from(): ClassicStorageFileApi
参数
无参数
返回
Classic-compatible object operation client.
示例
throwOnError
throwOnError(): this
参数
无参数
返回
Current client instance for chaining.
示例
upload
Upload a file to storage.
upload(path: string, fileBody: FileBody, fileOptions?: FileOptions): Promise<
| { data: { id: string; path: string; fullPath: string }; error: null }
| { data: null; error: StorageError }
>
type FileBody = File | Blob | ArrayBuffer | ArrayBufferView | FormData | string;
interface FileOptions {
cacheControl?: string;
contentType?: string;
metadata?: Record<string, any>;
upsert?: boolean; // default true
}
参数
Storage-relative path, for example `images/photo.jpg`.
File content.
Upload options. Classic mode defaults to `upsert: true`.
返回
CloudBase fileID. Use this value for download, deletion, and signed URLs.
Upload path.
Full path.
Error.
示例
update
Update an existing file.
update(path: string, fileBody: FileBody, fileOptions?: FileOptions): Promise<{ data, error }>
参数
Storage-relative path.
New file content.
Upload options.
返回
Update result.
Error.
示例
download
Download a file.
download(fileId: string, options?: TransformOptions): Promise<{ data: Blob; error: null } | { data: null; error: StorageError }>
interface TransformOptions {
width?: number;
height?: number;
quality?: number;
format?: "jpg" | "png" | "webp";
}
参数
Full CloudBase fileID.
Image transformation options.
返回
File content.
Error.
示例
remove
Delete one or more files.
remove(paths: string[]): Promise<{ data: FileObject[]; error: null } | { data: null; error: StorageError }>
参数
Full fileID array.
返回
Deletion result.
Error.
示例
move
Move a file to a new path.
move(fromPath: string, toPath: string): Promise<{ data: { message: string }; error: null } | { data: null; error: StorageError }>
参数
Source path.
Destination path.
返回
Operation result message.
Error.
示例
copy
Copy a file to a new path.
copy(fromPath: string, toPath: string): Promise<{ data: { path: string }; error: null } | { data: null; error: StorageError }>
参数
Source path.
Destination path.
返回
Destination path.
Error.
示例
createSignedUrl
Create a temporary access URL.
createSignedUrl(path: string, expiresIn: number, options?: { download?: string | boolean; transform?: TransformOptions }): Promise<{ data: { signedUrl: string }; error: null } | { data: null; error: StorageError }>
参数
Full fileID.
Expiration in seconds.
Download and image transform options.
返回
Signed access URL.
Error.
示例
createSignedUrls
Create temporary access URLs in batch.
createSignedUrls(paths: string[], expiresIn: number): Promise<{ data, error }>
参数
Full fileID array.
Expiration in seconds.
返回
Signed URL results.
Error.
示例
getPublicUrl
Get a public access URL.
getPublicUrl(path: string, options?: { download?: string | boolean; transform?: TransformOptions }): Promise<{ data: { publicUrl: string }; error: null } | { data: null; error: StorageError }>
参数
Full fileID.
返回
Access URL.
示例
info
Get file information.
info(pathOrFileId: string): Promise<{ data: FileInfo; error: null } | { data: null; error: StorageError }>
参数
Full fileID or relative path.
返回
File information.
Error.
示例
exists
Check whether a file exists.
exists(pathOrFileId: string): Promise<{ data: boolean; error: null } | { data: null; error: StorageError }>
参数
Full fileID or relative path.
返回
Whether it exists.
Error.
示例
createSignedUploadUrl
Create a signed upload URL.
createSignedUploadUrl(path: string): Promise<{ data, error }>
参数
Upload target path.
返回
Signed upload URL and CloudBase upload metadata.
Error.
示例
Type Definitions
type Result<T> =
| { data: T; error: null }
| { data: null; error: StorageError };
type FileBody = File | Blob | ArrayBuffer | ArrayBufferView | FormData | string;
interface UploadResult {
id: string;
path: string;
fullPath: string;
}
interface FileOptions {
cacheControl?: string;
contentType?: string;
metadata?: Record<string, any>;
upsert?: boolean;
}
interface TransformOptions {
width?: number;
height?: number;
quality?: number;
format?: "jpg" | "png" | "webp";
}
Migration Guide
If you are migrating from JS SDK v2 or older file APIs to the JS SDK v3 classic cloud storage API, use the following replacements:
| Legacy API | JS SDK v3 Classic Mode API |
|---|---|
app.uploadFile() | app.storage.from().upload() |
app.downloadFile() | app.storage.from().download() |
app.getTempFileURL() | app.storage.from().createSignedUrl() |
app.deleteFile() | app.storage.from().remove() |
When migrating, store the full fileID returned by upload() and use it for download, deletion, signed URLs, and file metadata queries.
Best Practices
1. Error handling
const { data, error } = await app.storage.from().upload("images/photo.jpg", file);
if (error) {
console.error("Operation failed:", error.message);
return;
}
2. Path rules
- Pass storage-relative paths when uploading, for example
images/photo.jpg. - For download, deletion, signed URLs, and file metadata queries, use the full
fileIDreturned by upload. - Do not start paths with
/or include consecutive/.