跳到主要内容

上传文件

接入完成后，最常见的开发操作就是上传文件。七彩云对象存储支持普通上传，也支持分片上传；并且单文件大小 不限制。

常见上传场景​

  • 用户上传附件
  • 程序自动备份
  • 后台批量导入资源
  • 上传图片、压缩包、安装包、视频等文件
  • 下载站或资源站上传可公开分发资源

上传前建议确认​

上传前可先确认：

  • Bucket 已创建
  • AccessKey / SecretKey 可用
  • Endpoint 已使用 https://s3.7caiyun.com
  • Region 已使用 us-west
  • 文件上传到正确的目录或路径
  • Bucket 权限符合业务要求
  • 工具或 SDK 的访问模式与当前环境兼容

对象 Key 规划建议​

对象存储通常没有真实目录，只有对象 Key。建议提前设计统一命名规则，例如：

  • images/2026/03/cover.jpg
  • downloads/app/v1.0.0/app.exe
  • backup/project-a/2026-03-16.sql.gz
  • user-uploads/{userId}/avatar.png

推荐规则：

  • 尽量避免根目录堆积大量文件
  • 按业务、日期、用户、资源类型分层
  • 路径命名尽量稳定，不要频繁变更
  • 文件名中避免特殊字符和空格

上传文件页面示意

图示说明：这是上传文件页面示意。即使你最终走 SDK 或脚本上传，也建议先用这个页面理解文件进入 Bucket 后的大致展示方式。

小文件上传​

对于普通小文件，通常可以直接通过 SDK 或工具上传。

适合：

  • 图片
  • 配置文件
  • 普通附件
  • 小型资源文件

大文件上传​

对于大文件，建议优先使用支持分片上传的方式。

七彩云对象存储：

  • 支持分片上传
  • 单文件大小不限制

优点：

  • 上传更稳定
  • 失败后更容易重试
  • 更适合网络不稳定的环境
  • 适合视频、安装包、压缩包等大体积文件

上传接口设计建议​

如果你自己封装业务接口，推荐服务端至少处理这些信息：

  • 目标 Bucket
  • 目标对象 Key
  • Content-Type
  • 是否覆盖同名文件
  • 上传完成后的访问方式
  • 是否需要生成公有链接或私有签名链接

元数据建议​

上传时如果 SDK 支持，建议按需设置：

  • Content-Type
  • Cache-Control
  • Content-Disposition
  • 自定义 Metadata

例如：

  • 图片、JS、CSS 等静态资源尽量设置正确的 Content-Type
  • 下载文件可按需设置 Content-Disposition
  • 可缓存资源设置合理的 Cache-Control

推荐实践​

  • 上传前先用小文件验证连接是否成功
  • 正式环境避免直接把文件都传到根目录
  • 大文件优先使用分片上传
  • 公开文件与私密文件尽量分不同 Bucket 管理
  • 对用户上传内容做类型与大小校验
  • 记录上传请求日志，便于排查失败原因
  • 下载分发型文件建议尽早规划固定目录结构

常见问题​

明明上传成功了，但访问失败​

优先检查：

  • Bucket 是公有还是私有
  • 访问链接使用的是主机模式还是路径模式
  • 对象 Key 是否正确
  • 是否使用了正确的域名或签名方式

为什么建议把大文件走分片上传？​

因为大文件上传更容易受网络波动影响，分片上传更利于重试、恢复和稳定性控制。

相关页面​