cloud-storage-web

仓库: tencentcloudbase/skills
安装量: 519
排名: #2075

安装

npx skills add https://github.com/tencentcloudbase/skills --skill cloud-storage-web
Cloud Storage 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).
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)
How to use this skill (for a coding 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
)
SDK Initialization
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
File Upload (uploadFile)
Basic Usage
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
}
Advanced Upload with Progress
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
}
}
)
;
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
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"
CORS Configuration
⚠️ 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
Temporary Download URLs (getTempFileURL)
Basic Usage
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
}
}
)
;
Multiple Files
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
}
]
}
)
;
Parameters
Parameter
Type
Required
Description
fileList
Array
Yes
Array of file objects
fileList Item Structure
Parameter
Type
Required
Description
fileID
string
Yes
Cloud storage file ID
maxAge
number
Yes
URL validity period in seconds
Response Structure
{
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
File Deletion (deleteFile)
Basic Usage
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
)
;
}
}
)
;
Multiple Files
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
Yes
Array of file IDs to delete
Response Structure
{
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)
Basic Usage
const
result
=
await
app
.
downloadFile
(
{
fileID
:
"cloud://env-id/folder/filename.jpg"
}
)
;
// File is downloaded to browser default download location
Parameters
Parameter
Type
Required
Description
fileID
string
Yes
Cloud storage file ID
Response Structure
{
// Success response (no specific data returned)
// File is downloaded to browser
}
Best Practices
Use for user-initiated downloads (save file dialogs)
For programmatic file access, use
getTempFileURL
instead
Handle download errors appropriately
Error Handling
All storage operations should include proper error handling:
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
)
;
}
Common Error Codes
INVALID_PARAM
- Invalid parameters
PERMISSION_DENIED
- Insufficient permissions
RESOURCE_NOT_FOUND
- File not found
SYS_ERR
- System error
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
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
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
← 返回排行榜