对象存储命名规范参考（小白也能看懂）#

原则 1：用路径表示层级，模拟文件夹#

对象存储虽然没有真正的”文件夹”，但用斜杠 / 分隔路径，就能模拟出目录结构，还能让云厂商的”文件夹浏览”功能正常工作。

1
images/user/avatar/2026/08/dgh_001.jpg

• images → 一级目录（图片）
• user/avatar → 二级、三级目录（用户头像）
• 2026/08 → 按时间分层
• dgh_001.jpg → 最终文件名

原则 2：按”从大类到小类”的顺序排#

路径从左到右，应该是越来越具体：

1
{业务}/{模块}/{子类}/{时间}/{唯一标识}{扩展名}

反例（顺序颠倒，很难读）：

1
dgh_001/avatar/user/images/2026/08.jpg   ❌ 这是什么鬼？

原则 3：唯一标识要能溯源#

同一个对象，Key 必须唯一且可溯源。推荐的标识符优先级：

1. UUID：最推荐，全球唯一、无序，适合海量文件
2. 时间戳 + 随机数：如 20260816_183000_ab12cd
3. 业务 ID：如 user_10001，方便按用户查
4. 自增 ID：不太推荐，容易冲突且暴露数量

原则 4：小写 + 连字符，统一风格#

• 一律用小写字母
• 单词之间用短横线 - 连接（不要用下划线、空格、中文）
• 文件扩展名保持全小写

1
blog-cover-2026-08.jpg      ✅
2
blogCover202608.jpg         ❌ 混用大小写
3
blog_cover_2026_08.jpg      ❌ 用了下划线
4
2026年8月封面图.jpg         ❌ 中文+空格

模板 1：用户上传的文件（图片/头像/证件）#

1
{业务}/user/{userId}/avatar/{yyyy}/{mm}/{uuid}.{ext}

示例：

1
blog/user/u_10001/avatar/2026/08/6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c.jpg

模板 2：内容系统的图片（封面/文章配图）#

1
{业务}/content/{type}/{yyyy}/{mm}/{uuid}.{ext}

示例：

1
blog/content/cover/2026/08/8c2e3f4a-5b6c-4d7e-9f8a-1b2c3d4e5f6a.webp

模板 3：日志文件（按时间归档）#

1
logs/{service}/{yyyy}/{mm}/{dd}/{yyyy-mm-dd_hh}_{uuid}.log

示例：

1
logs/api-server/2026/08/16/2026-08-16_18_api-6f1a2b3c.log

模板 4：备份文件#

1
backup/{db-name}/{yyyy}/{mm}/{db-name}_{yyyy-mm-dd}_{uuid}.sql.gz

示例：

1
backup/mysql-main/2026/08/mysql-main_2026-08-16_7a8b9c0d.sql.gz

坑 1：文件覆盖#

如果你用固定名字保存，比如用户头像永远叫 avatar.jpg，那么新头像会覆盖旧头像，旧图就没了。

解法：文件名里加上 userId + uuid，或者存多版本。

坑 2：大小写混用导致防盗链/缓存问题#

CDN 的缓存 key 通常区分大小写。Avatar.jpg 和 avatar.jpg 会被当成两个文件，浪费缓存、还容易出 bug。

解法：全小写，统一风格。

坑 3：中文文件名#

中文文件名在 URL 里会变成一堆 % 编码，不仅难看，有些环境还会解析出错。

解法：一律用英文 + 数字 + 短横线命名，中文信息放到数据库字段里存。

坑 4：扩展名不规范#

• 图片要用对的类型：.jpg、.png、.webp
• 字体文件要用 .woff2、.ttf（不要用 .txt 存字体）
• 压缩包用 .zip、.tar.gz

之前排查过：字体文件如果 Content-Type 是 text/plain，浏览器就会拒载。规范命名 + 正确 Content-Type 缺一不可。

坑 5：没有前缀隔离，混成一团#

一个 Bucket 里塞了图片、视频、日志、备份……互相干扰，权限也不好控。

解法：用顶层前缀分业务，如 images/、videos/、logs/，配合云厂商的前缀级权限策略，一个 Bucket 也能安全隔离。