Shopify 知识库 · 概念
文件与媒体库：上传、格式限制与引用
说明 Shopify 后台 Content > Files 的上传与管理、图片视频与一般文件的格式和大小限制（官方页数值不一致处并列）、套餐存储上限、文件名规则与替换删除的影响、file_reference 类型 metafield 与主题对文件的引用、CDN 链接、图片尺寸建议与替代文本，只写官方页所读。
Shopify 后台的 Content > Files 是店铺的文件库：上传图片、视频、3D 模型与可下载文件，之后被商品、页面、主题设置或 metafield 引用。它解决“素材放在哪、能传多大、被谁用着”；它不负责素材是否清晰、授权是否合规，也不替你决定商品页应该展示哪些图（那是商品展示的内容问题）。本文所有数值核验于 2026-09-29，官方页之间不一致的并列列出。
本库哪些内容依赖它
- 商品展示与商品视频：图片、视频、3D 的规格与替代文字，本文的图片与视频数值与它们并列一致；
- Dawn 商品媒体：主题读取
product.media的方式； - 自定义数据：
file_reference类型 metafield 的定义与读取； - 商品与变体、商品导入导出：商品上的媒体与 CSV 图片链接；
- 翻译与本地化：图片、视频与文件的按语言替换；
- 通知邮件：邮件 logo 等素材的来源为后台定制项，本文未核验其与 Files 的关系。
本文是该平台机制的权威来源，其他文章只写各自页面语境下的用法。
核心对象与概念
| 对象 | 含义 | 备注 |
|---|---|---|
| File | Files 页中的一项资源 | Admin API 的 File 接口，含 alt、fileStatus、createdAt、updatedAt、fileErrors |
| 内容类型 | fileCreate 的 contentType | IMAGE、VIDEO、EXTERNAL_VIDEO、MODEL_3D、FILE（PDF 等一般文件） |
| MediaImage / GenericFile | 文件的 GID 类型 | metafield 引用值形如 gid://shopify/MediaImage/123 |
| 外部视频 | YouTube 或 Vimeo 链接 | shopify.dev 写明不占店铺存储配额 |
| 焦点（focal point） | 裁切时要保留的区域 | 可在主题编辑器或 Files 页设置 |
| 文件链接 | Files 页每个文件的 Link 按钮复制出的 CDN 链接 | 见下文 |
在哪里配置
- 上传：Content > Files > Upload files，一次最多选 20 个文件；手机端为菜单 > Content > Files > Upload files。官方页未写拖拽上传与网址导入（摘要读取，未逐字复核）。
- 管理：官方页列出的操作有复制链接、按文件名与类型搜索，以及按大小、类型、Used in、替代文本筛选；可添加 alt text、设焦点、更换视频封面、通过 URL Handle 重命名、批量勾选删除。
- 商品引用：在商品页的媒体区点 Select existing 选择已有文件，或点 Add from URL。每个商品最多 250 个图片、3D 模型或视频。
- 主题引用：主题编辑器里可直接上传图片，官方也写明可在 Files 页上传；
image_picker设置的选项自动来自 Files。官方提醒：只应把打算公开展示的内容（商品媒体、下载内容、店面图片）传到 Files。 - 替代文本：商品页选媒体后点 Add alt text；手机端为 Shopify app 的媒体 Information 标签；支持 CSV 批量上传。
与主题、Liquid 和 API 的连接
| 入口 | 官方页所写 |
|---|---|
Liquid file_url | 返回 Files 页文件的 CDN 链接，例：{{ 'disclaimer.pdf' | file_url }} |
Liquid image_url | 返回图片 CDN 链接，必须指定 width 或 height（否则报错），上限 5760px；图片不会被放大到超过原尺寸；format 只支持 pjpg 与 jpg，且只能 png 转 jpg / pjpg、jpg 转 pjpg |
image_picker 设置 | 返回 image 对象；未选择或所选文件已不存在时返回 nil |
metafield file_reference | Liquid 返回 generic_file 对象，或（仅图片与视频）media 对象 |
generic_file 对象 | 属性 alt、id、media_type（恒为 generic_file）、position、preview_image、url |
| Admin API | fileCreate（需 write_files、write_themes、write_images；originalSource 与 contentType 必填；alt 最多 512 字符；单批最多 250 个；异步处理，需查 fileStatus）、fileUpdate、fileDelete（需 write_files）；大文件与服务器托管内容官方建议用 stagedUploadsCreate |
metafield 引用：数据类型页写明 file_reference 默认引用 GenericFile，可用验证选项加入其他类型；列表版本为 list.file_reference，值为 GID 字符串数组。验证选项页写 file_type_options 的有效值为 Image 与 Video，并注明留空则不限类型；该页示例又提到 PDF，与列出的有效值不完全一致，并列记录。定义与读取的整体机制见自定义数据，本文不重复。file_reference 在数据类型页标注可翻译、不可按市场本地化。
限制、数值与易错点
图片（官方页互不一致，并列）
| 来源页 | 格式 | 大小 | 像素与比例 |
|---|---|---|---|
| Uploading and managing files | JPEG、PNG、WEBP、HEIC、GIF | 20 MB | 25 MP；宽高比 100:1 至 1:100 |
| Product media types | PNG、JPEG、PSD、TIFF、BMP、GIF、SVG、HEIC、WebP（GIF 与 WebP 可动画） | 20 MB | 5000 × 5000 px 或 25 MP；方形图推荐 2048 × 2048 |
| Uploading images（主题图片） | JPEG（含渐进式）、PNG、GIF、HEIC、WebP | 20 MB | 限制写 20 MP，同页又建议上传至 5000 × 5000 px 或 25 MP 的高分辨率图 |
| shopify.dev Product media | PNG、GIF、JPEG、WEBP、HEIC | 20 MB | 4472 × 4472 px（20 MP）；比例 100:1 至 1:100；推荐 2048 × 2048 |
本文不选边。准备素材时可保守取交集：单文件不超过 20 MB、不超过较小的像素上限；以上传时后台的实际提示与 API 返回为准。与商品展示所记三处不一致相同，另加主题图片页与 shopify.dev 的 20 MP 表述。
视频、3D 与一般文件
- 视频：Files 页写 MOV、MP4、WEBM，最大 1 GB、10 分钟，宽高 100–4096 px，最高 120 fps；商品媒体类型页写最高 4K（4096 × 2160），上传后转为 mp4 或 HLS；shopify.dev 写最大 3840 × 2160，并注明应用每店每周最多创建 1,000 个视频。这些数值与商品视频一致，分辨率上限不一致处见该文，不重复。
- 3D 模型：GLB 与 USDZ，最大 500 MB；超过 15 MB 会被自动优化（商品媒体类型页）。
- 一般文件：官方页写“除 HTML 外的任何文件类型”，最大 20 MB（摘要读取）。
- 试用套餐：摘要读到仅允许 JS、CSS、GIF、JPEG、PNG、JSON、CSV、PDF、WebP、HEIC，且 PDF 需验证邮箱；未逐字复核，使用前以官方页为准。
存储与数量（Files 页，按套餐）
| 套餐 | 总存储 | 视频存储 | 视频与 3D 数量 |
|---|---|---|---|
| Starter / Pause and Build / Retail / Basic 与 Partner 开发店 | 100 GB | 50 GB | 250 |
| Grow | 300 GB | 500 GB | 1,000 |
| Advanced | 500 GB | 500 GB | 5,000 |
| Plus 与 Partner Plus 沙盒店 | 1 TB | 2 TB | 50,000 |
| Enterprise | 10 TB | 10 TB | 100,000 |
Partner Plus 沙盒店的视频存储单列为 60 GB。表中 Grow 的视频存储大于总存储，这是页面原表如此，含义未核验。Plus 与 Enterprise 可付费增加存储，价格随时间变化，本文不写。套餐口径见套餐。
文件名、替换与链接
- 图片文件名不能以
pico、icon、thumb、testing、small、compact、medium、large、grande结尾，官方说明这些结尾可能被 CDN 误当作图片转换请求；文件名不能以句点开头；重名或特殊字符与 CDN 冲突时系统会自动追加唯一标识。 - 替换文件：只能用相同格式替换（JPG 换 JPG）。官方写明文件名不变但链接会变，旧链接不再可用。含义是：任何写死旧 CDN 链接的地方会失效，这是本文的推论，官方页未展开。
- 商品 CSV 导入时，指向 Files 区的链接会被重新下载并产生重复图片，见商品导入导出。
删除的影响
- Files 页勾选文件、点删除并确认即可批量删除；官方页读取范围内没有关于“文件正在被使用”的警告文字。
- 在商品页移除媒体只是解除引用，官方写明不会从店铺删除；要真正删除必须在 Files 页操作。
fileDelete官方写明：永久删除且不可撤销；文件会立刻不再显示于任何使用处；删除商品关联的文件时，会自动移除引用并重排该商品剩余媒体。- 主题
image_picker所选文件不存在时，Liquid 得到nil，主题需处理空值。 - 文件被 metafield 引用后删除会怎样，本次未读到，未核验。删除前用 Used in 筛选自查，但该筛选覆盖哪些引用类型未核验（搜索摘要只提到可看到商品与主题中的使用）。
CDN 与 URL
Files 页复制的链接与 file_url 都是 CDN 链接，形如 //店铺域名/cdn/shop/files/文件名?v=版本号（shopify.dev 示例）。主题平台页写明 CDN 与店面在同一域名下、使用 /cdn 路径，并说明不必在主题里写死 cdn.shopify.com；asset_url 会自动追加版本参数，缓存更新靠 v 参数。官方写明 Imagery 服务会检测客户端支持的图片格式并以最佳格式显示。本文不写任何性能收益的判断。
图片格式与尺寸建议
- 官方推荐方形商品图 2048 × 2048 px；同页强调集合页要靠一致的宽高比获得统一显示。
- 主题图片页建议上传“不超过 5000 × 5000 px 或 25 MP 的高分辨率图”，与同页 20 MP 的限制并存，见上表。
- 需要多个尺寸时用
image_url传width，不要上传多份不同尺寸的文件。 - 视频建议宽高比 16:9、9:16、4:3、3:4 或 1:1，H.264 与 AAC、MP3、Opus 为文件上传页所建议，详见商品视频。
替代文本
- 官方写明 alt 最多允许 512 个字符，建议 125 个字符以内，要求简短且描述性；用途包括媒体加载失败时显示、辅助视障顾客，也可能有利于搜索。
fileCreate的alt同样上限 512。 - 媒体编辑器可为没有描述的图片建议 alt，接受后保存到文件。
- 商品页上的替代文本写法与必填口径见商品展示；无障碍基线见无障碍合规基线与 WCAG；搜索侧的图片优化见店面 SEO 框架。
- 在 Files 页改 alt 与在商品页改 alt 是否同一字段，官方页未明写，未核验，改后应到商品页复查。
验证一次
- 在测试店铺 Content > Files 上传一张 JPEG、一个 PDF、一个 MP4，记录上传提示、处理状态与 Link 复制出的链接；
- 尝试上传超出某一个数值的图片（如 21 MB 或大于 4472 px 的图），记录后台实际提示，以此回填“并列数值”里哪一处生效；
- 把图片加入商品，再加入主题
image_picker与一个file_referencemetafield，用 Used in 筛选查看显示； - 用同格式替换一次，确认旧链接失效、名称不变；
- 在商品页移除媒体，确认文件仍在 Files；再在 Files 删除，检查商品页、主题设置与 metafield 页面的表现与 Liquid 空值；
- 为图片添加 alt，在店面查看源码；
- 每步记录时间、套餐与所见结果。
待继续完善
- 各来源图片与视频数值的实测回填；
- metafield 引用被删除后的行为、Used in 筛选范围；
- Files 与商品页 alt 是否同一字段；
- 试用套餐限制全表与一般文件类型限制的逐字复核；
- 主题与页面正文（富文本）对 Files 的引用方式；
- 未在真实店铺上传、替换或删除文件。