# 静态资源与对象存储

本规范适用于网站图片、字体、音视频、附件及运行时生成文件。目标是让资源体积可控、来源可追踪、交付可复现，并使开发和生产环境不依赖某个人电脑上的文件。仓库边界和 `.gitignore` 细则见 [Git、资源与持久化](../workflow/git-repository-and-assets.md)。

## 格式、尺寸与压缩

- 网页栅格图片优先使用经过压缩的 WebP，并按实际展示尺寸生成所需规格；不要把原始大图交给浏览器仅靠 CSS 缩小。需要透明或无损细节时按效果选择合适编码；确有兼容性要求时提供经过压缩的回退格式。
- 简单图标优先使用图标库或可审阅的文本 SVG。外部 SVG 先确认来源与安全性，不把不可信 SVG 当作可直接嵌入页面的代码。字体只加载实际使用的字重和字符范围，避免为一个图标引入整套字体。
- 音视频按播放场景转码，提供适合的清晰度与封面；不要把拍摄原件直接作为网页资源。上传时检查文件类型、尺寸和大小，生成派生规格后再用于页面展示。
- 为图片设置明确的展示尺寸或比例，避免加载后推动布局。首屏关键资源优先加载；屏外资源按需加载。压缩前后检查可读性、清晰度和文件大小，不为极小的体积收益破坏内容。

## 二进制不直接入库

图片、字体、音视频、PDF、压缩包、模型、数据库文件和其他二进制资源不得直接提交到 Git，包括“体积很小”的品牌素材。Git LFS 不作为绕过这条规则的默认办法。版本控制保留源码、文本 SVG、配置、资源清单及可重复执行的处理脚本；网页资源的二进制原件和产物放到受管理的对象存储，并记录来源、许可、负责人和替换方式。构建制品和数据库备份使用各自的制品或备份存储，不混进网页资源库。

`.gitignore` 应覆盖项目实际产生的上传目录、下载缓存、转码输出和其他本地二进制产物，提交前仍需审阅暂存清单。不要只靠忽略规则：已被追踪的二进制不会自动从 Git 历史消失。

## 对象存储与可复现环境

- 产品需要图片或文件时，配置 OSS／S3 兼容对象存储及必要的访问域名；公开静态资源可按流量和地域需求接入 CDN。开发、测试和生产使用各自的 Bucket 或隔离前缀，密钥从项目约定的安全配置渠道注入，不写入仓库和前端构建产物。
- 公开、不可变资源使用带版本或内容标识的对象键，再设置与更新策略一致的缓存；替换资源时更换键或明确执行失效。私有上传默认保持私有，由服务端鉴权后提供短期访问，不以公开 URL 代替权限判断。
- 页面和服务引用可配置的对象键、资源清单或正式访问地址，不能依赖 `/Users/...`、个人下载目录、某台机器的绝对路径，或未声明的本地文件服务。正式部署从干净检出加项目配置即可定位所需资源。
- 本地开发可使用受控测试 Bucket 或可复现的本地 S3 兼容服务；所需启动配置、初始化步骤和最小测试资源要有说明。不得要求开发者复制某个人电脑上的隐藏目录才能运行。没有文件功能的项目不必预建 OSS 服务。

## 交付检查

选一条实际页面或上传链路，确认资源由正确环境提供、请求成功、格式和体积合适、缓存更新后可见；再从干净检出环境验证服务可以启动且不依赖个人文件。检查 Git 暂存清单不含二进制、上传内容或密钥。运行时上传与其元数据、授权、重试和清理规则还应遵守 [Git、资源与持久化](../workflow/git-repository-and-assets.md)。