cloud-storage-web

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Storage Web SDK

CloudBase云存储Web SDK

Use this skill when building web applications that need to upload, download, or manage files using CloudBase cloud storage via the

@cloudbase/js-sdk

(Web SDK).

当你构建需要通过

@cloudbase/js-sdk

（Web SDK）操作CloudBase云存储来上传、下载或管理文件的Web应用时，可以使用本技能。

When to use this skill

适用场景

Use this skill for file storage operations in web applications when you need to:

Upload files from web browsers to CloudBase cloud storage
Generate temporary download URLs for stored files
Delete files from cloud storage
Download files from cloud storage to local browser

Do NOT use for:

Mini-program file operations (use mini-program specific skills)
Backend file operations (use Node SDK skills)
Database operations (use database skills)

当你需要在Web应用中执行以下文件存储操作时，可以使用本技能：

从Web浏览器上传文件至CloudBase云存储
为已存储的文件生成临时下载URL
从云存储中删除文件
将云存储中的文件下载至本地浏览器

不适用场景：

小程序文件操作（请使用小程序专属技能）
后端文件操作（请使用Node SDK技能）
数据库操作（请使用数据库技能）

How to use this skill (for a coding agent)

如何使用本技能（面向编码Agent）

Initialize CloudBase SDK
- Ask the user for their CloudBase environment ID
- Always use the standard initialization pattern shown below
Choose the right storage method
- ```
uploadFile
```
  - For uploading files from browser to cloud storage
- ```
getTempFileURL
```
  - For generating temporary download links
- ```
deleteFile
```
  - For deleting files from storage
- ```
downloadFile
```
  - For downloading files to browser
Handle CORS requirements
- Remind users to add their domain to CloudBase console security domains
- This prevents CORS errors during file operations
Follow file path rules
- Use valid characters:
```
[0-9a-zA-Z]
```
  ,
```
/
```
  ,
```
!
```
  ,
```
-
```
  ,
```
_
```
  ,
```
.
```
  ,
```
 
```
  ,
```
*
```
  , Chinese characters
- Use
```
/
```
  for folder structure (e.g.,
```
folder/file.jpg
```
  )

初始化CloudBase SDK
- 向用户获取其CloudBase环境ID
- 始终使用下方展示的标准初始化模板
选择合适的存储方法
- ```
uploadFile
```
  - 用于从浏览器上传文件至云存储
- ```
getTempFileURL
```
  - 用于生成临时下载链接
- ```
deleteFile
```
  - 用于从云存储中删除文件
- ```
downloadFile
```
  - 用于将文件下载至浏览器
处理CORS要求
- 提醒用户将其域名添加至CloudBase控制台的安全域名列表
- 这可以避免文件操作过程中出现CORS错误
遵循文件路径规则
- 使用有效字符：
```
[0-9a-zA-Z]
```
  、
```
/
```
  、
```
!
```
  、
```
-
```
  、
```
_
```
  、
```
.
```
  、空格、
```
*
```
  、中文字符
- 使用
```
/
```
  构建文件夹结构（例如：
```
folder/file.jpg
```
  ）

SDK Initialization

SDK初始化

javascript

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // Replace with your CloudBase environment ID
});

Initialization rules:

Always use synchronous initialization with the pattern above
Do not lazy-load the SDK with dynamic imports
Keep a single shared
```
app
```
instance across your application

javascript

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的CloudBase环境ID
});

初始化规则：

始终使用上述同步初始化方式
不要通过动态导入延迟加载SDK
在应用中保持单个共享的
```
app
```
实例

File Upload (uploadFile)

文件上传（uploadFile）

Basic Usage

基础用法

javascript

const result = await app.uploadFile({
  cloudPath: "folder/filename.jpg", // File path in cloud storage
  filePath: fileInput.files[0],     // HTML file input element
});

// Result contains:
{
  fileID: "cloud://env-id/folder/filename.jpg", // Unique file identifier
  // ... other metadata
}

javascript

const result = await app.uploadFile({
  cloudPath: "folder/filename.jpg", // 云存储中的文件路径
  filePath: fileInput.files[0],     // HTML文件输入元素
});

// 返回结果包含：
{
  fileID: "cloud://env-id/folder/filename.jpg", // 唯一文件标识符
  // ... 其他元数据
}

Advanced Upload with Progress

带进度的高级上传

javascript

const result = await app.uploadFile({
  cloudPath: "uploads/avatar.jpg",
  filePath: selectedFile,
  method: "put", // "post" or "put" (default: "put")
  onUploadProgress: (progressEvent) => {
    const percent = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`Upload progress: ${percent}%`);
    // Update UI progress bar here
  }
});

javascript

const result = await app.uploadFile({
  cloudPath: "uploads/avatar.jpg",
  filePath: selectedFile,
  method: "put", // "post" 或 "put"（默认值："put"）
  onUploadProgress: (progressEvent) => {
    const percent = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`上传进度：${percent}%`);
    // 在此处更新UI进度条
  }
});

Parameters

参数说明

Parameter	Type	Required	Description
`cloudPath`	string	Yes	Absolute path with filename (e.g., "folder/file.jpg")
`filePath`	File	Yes	HTML file input object
`method`	"post" \| "put"	No	Upload method (default: "put")
`onUploadProgress`	function	No	Progress callback function

参数	类型	是否必填	描述
`cloudPath`	string	是	带文件名的绝对路径（例如："folder/file.jpg"）
`filePath`	File	是	HTML文件输入对象
`method`	"post" \| "put"	否	上传方式（默认值："put"）
`onUploadProgress`	function	否	进度回调函数

Cloud Path Rules

云路径规则

Valid characters:
```
[0-9a-zA-Z]
```
,
```
/
```
,
```
!
```
,
```
-
```
,
```
_
```
,
```
.
```
,
```
 
```
,
```
*
```
, Chinese characters
Invalid characters: Other special characters
Structure: Use
```
/
```
to create folder hierarchy

Examples:

```
"avatar.jpg"
```
```
"uploads/avatar.jpg"
```
```
"user/123/avatar.jpg"
```

有效字符：
```
[0-9a-zA-Z]
```
、
```
/
```
、
```
!
```
、
```
-
```
、
```
_
```
、
```
.
```
、空格、
```
*
```
、中文字符
无效字符：其他特殊字符
结构：使用
```
/
```
创建文件夹层级

示例:

```
"avatar.jpg"
```
```
"uploads/avatar.jpg"
```
```
"user/123/avatar.jpg"
```

CORS Configuration

CORS配置

⚠️ IMPORTANT: To prevent CORS errors, add your domain to CloudBase console:

Go to CloudBase Console → Environment → Security Sources → Security Domains

Add your frontend domain (e.g.,

https://your-app.com

http://localhost:3000

)

If CORS errors occur, remove and re-add the domain

⚠️ 重要提示： 为避免CORS错误，请将你的域名添加至CloudBase控制台：

进入CloudBase控制台 → 环境 → 安全来源 → 安全域名
添加你的前端域名（例如：
```
https://your-app.com
```
、
```
http://localhost:3000
```
）
若出现CORS错误，可删除域名后重新添加

Temporary Download URLs (getTempFileURL)

临时下载URL（getTempFileURL）

Basic Usage

基础用法

javascript

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/folder/filename.jpg",
      maxAge: 3600 // URL valid for 1 hour (seconds)
    }
  ]
});

// Access the download URL
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("Download URL:", file.tempFileURL);
    // Use this URL to download or display the file
  }
});

javascript

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/folder/filename.jpg",
      maxAge: 3600 // URL有效期1小时（秒）
    }
  ]
});

// 获取下载URL
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("下载URL:", file.tempFileURL);
    // 使用该URL下载或展示文件
  }
});

Multiple Files

多文件处理

javascript

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/image1.jpg",
      maxAge: 7200 // 2 hours
    },
    {
      fileID: "cloud://env-id/document.pdf",
      maxAge: 86400 // 24 hours
    }
  ]
});

javascript

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/image1.jpg",
      maxAge: 7200 // 2小时
    },
    {
      fileID: "cloud://env-id/document.pdf",
      maxAge: 86400 // 24小时
    }
  ]
});

Parameters

参数说明

Parameter	Type	Required	Description
`fileList`	Array	Yes	Array of file objects

参数	类型	是否必填	描述
`fileList`	Array	是	文件对象数组

fileList Item Structure

fileList项结构

Parameter	Type	Required	Description
`fileID`	string	Yes	Cloud storage file ID
`maxAge`	number	Yes	URL validity period in seconds

参数	类型	是否必填	描述
`fileID`	string	是	云存储文件ID
`maxAge`	number	是	URL有效期（秒）

Response Structure

返回结果结构

javascript

{
  code: "SUCCESS",
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg",
      tempFileURL: "https://temporary-download-url"
    }
  ]
}

javascript

{
  code: "SUCCESS",
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg",
      tempFileURL: "https://temporary-download-url"
    }
  ]
}

Best Practices

最佳实践

Set appropriate
```
maxAge
```
based on use case (1 hour to 24 hours)
Handle
```
SUCCESS
```
/
```
ERROR
```
codes in response
Use temporary URLs for private file access
Cache URLs if needed, but respect expiration time

根据使用场景设置合适的
```
maxAge
```
（1小时至24小时）
处理返回结果中的
```
SUCCESS
```
/
```
ERROR
```
状态码
使用临时URL访问私有文件
若需要可缓存URL，但需注意有效期

File Deletion (deleteFile)

文件删除（deleteFile）

Basic Usage

基础用法

javascript

const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/folder/filename.jpg"
  ]
});

// Check deletion results
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("File deleted:", file.fileID);
  } else {
    console.error("Failed to delete:", file.fileID);
  }
});

javascript

const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/folder/filename.jpg"
  ]
});

// 检查删除结果
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("文件已删除:", file.fileID);
  } else {
    console.error("删除失败:", file.fileID);
  }
});

Multiple Files

多文件删除

javascript

const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/old-avatar.jpg",
    "cloud://env-id/temp-upload.jpg",
    "cloud://env-id/cache-file.dat"
  ]
});

javascript

const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/old-avatar.jpg",
    "cloud://env-id/temp-upload.jpg",
    "cloud://env-id/cache-file.dat"
  ]
});

Parameters

参数说明

Parameter	Type	Required	Description
`fileList`	Array<string>	Yes	Array of file IDs to delete

参数	类型	是否必填	描述
`fileList`	Array<string>	是	待删除的文件ID数组

Response Structure

返回结果结构

javascript

{
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg"
    }
  ]
}

javascript

{
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg"
    }
  ]
}

Best Practices

最佳实践

Always check response codes before assuming deletion success
Use this for cleanup operations (old avatars, temp files, etc.)
Consider batching multiple deletions for efficiency

始终检查返回状态码，不要默认删除成功
用于清理操作（旧头像、临时文件等）
考虑批量删除多个文件以提升效率

File Download (downloadFile)

文件下载（downloadFile）

Basic Usage

基础用法

javascript

const result = await app.downloadFile({
  fileID: "cloud://env-id/folder/filename.jpg"
});

// File is downloaded to browser default download location

javascript

const result = await app.downloadFile({
  fileID: "cloud://env-id/folder/filename.jpg"
});

// 文件将下载至浏览器默认下载位置

Parameters

参数说明

Parameter	Type	Required	Description
`fileID`	string	Yes	Cloud storage file ID

参数	类型	是否必填	描述
`fileID`	string	是	云存储文件ID

Response Structure

返回结果结构

javascript

{
  // Success response (no specific data returned)
  // File is downloaded to browser
}

javascript

{
  // 成功响应（无特定返回数据）
  // 文件将下载至浏览器
}

Best Practices

最佳实践

Use for user-initiated downloads (save file dialogs)
For programmatic file access, use
```
getTempFileURL
```
instead
Handle download errors appropriately

用于用户主动发起的下载（保存文件对话框）
若需程序化访问文件，请使用
```
getTempFileURL
```
替代
妥善处理下载错误

Error Handling

错误处理

All storage operations should include proper error handling:

javascript

try {
  const result = await app.uploadFile({
    cloudPath: "uploads/file.jpg",
    filePath: selectedFile
  });

  if (result.code) {
    // Handle error
    console.error("Upload failed:", result.message);
  } else {
    // Success
    console.log("File uploaded:", result.fileID);
  }
} catch (error) {
  console.error("Storage operation failed:", error);
}

所有存储操作都应包含完善的错误处理：

javascript

try {
  const result = await app.uploadFile({
    cloudPath: "uploads/file.jpg",
    filePath: selectedFile
  });

  if (result.code) {
    // 处理错误
    console.error("上传失败:", result.message);
  } else {
    // 成功
    console.log("文件已上传:", result.fileID);
  }
} catch (error) {
  console.error("存储操作失败:", error);
}

Common Error Codes

常见错误码

```
INVALID_PARAM
```
- Invalid parameters
```
PERMISSION_DENIED
```
- Insufficient permissions
```
RESOURCE_NOT_FOUND
```
- File not found
```
SYS_ERR
```
- System error

```
INVALID_PARAM
```
- 参数无效
```
PERMISSION_DENIED
```
- 权限不足
```
RESOURCE_NOT_FOUND
```
- 文件不存在
```
SYS_ERR
```
- 系统错误

Best Practices

最佳实践

File Organization: Use consistent folder structures (
```
uploads/
```
,
```
avatars/
```
,
```
documents/
```
)
Naming Conventions: Use descriptive filenames with timestamps if needed
Progress Feedback: Show upload progress for better UX
Cleanup: Delete temporary/unused files to save storage costs
Security: Validate file types and sizes before upload
Caching: Cache download URLs appropriately but respect expiration
Batch Operations: Use arrays for multiple file operations when possible

文件组织：使用统一的文件夹结构（
```
uploads/
```
、
```
avatars/
```
、
```
documents/
```
）
命名规范：使用描述性文件名，必要时添加时间戳
进度反馈：展示上传进度以提升用户体验
清理策略：删除临时/无用文件以节省存储成本
安全校验：上传前验证文件类型和大小
缓存策略：合理缓存下载URL，但需遵守有效期
批量操作：尽可能使用数组执行多文件操作

Performance Considerations

性能考量

File Size Limits: Be aware of CloudBase file size limits
Concurrent Uploads: Limit concurrent uploads to prevent browser overload
Progress Monitoring: Use progress callbacks for large file uploads
Temporary URLs: Generate URLs only when needed, with appropriate expiration

文件大小限制：注意CloudBase的文件大小限制
并发上传：限制并发上传数量以避免浏览器过载
进度监控：对大文件上传使用进度回调
临时URL：仅在需要时生成URL，并设置合适的有效期

Security Considerations

安全考量

Domain Whitelisting: Always configure security domains to prevent CORS issues
Access Control: Use appropriate file permissions (public vs private)
URL Expiration: Set reasonable expiration times for temporary URLs
User Permissions: Ensure users can only access their own files when appropriate

域名白名单：始终配置安全域名以避免CORS问题
访问控制：使用合适的文件权限（公开/私有）
URL有效期：为临时URL设置合理的过期时间
用户权限：确保用户仅能访问自己的文件（若适用）