Shopify如何通过image_picker添加图片？代码报错排查

云上老周

2026-8-30

Shopify image_picker 功能报错排查与修复

你提供的字段定义片段本身基础语法没有问题，运行报错可按以下优先级逐一排查修复：

放置位置错误：image_picker 是Shopify主题配置专属字段类型，仅允许出现在两个位置：一是主题根目录config/settings_schema.json的配置组settings数组内，二是section/block文件中{% schema %}标签包裹的JSON结构内，直接写在普通Liquid模板、JS代码段中会直接报语法或类型错误。
字段配置缺项：单独的id和type属性在新版Shopify主题编辑器中不足以正常渲染配置项，必须补充label属性声明字段显示名称，否则会触发schema校验失败。
JSON结构错误：字段不能独立裸露在结构中，必须嵌套在对应配置块的settings数组下，两种场景的正确写法如下：
1. 全局主题配置（config/settings_schema.json）场景：

[
  {
    "name": "站点全局配置",
    "settings": [
      {
        "id": "image",
        "type": "image_picker",
        "label": "站点默认分享图"
      }
    ]
  }
]

Section模块配置场景：

{% schema %}
{
  "name": "自定义图片展示模块",
  "settings": [
    {
      "id": "image",
      "type": "image_picker",
      "label": "模块主图"
    }
  ]
}
{% endschema %}

前端调用逻辑错误：image_picker类型字段保存后返回的是图片对象而非直接的图片地址，直接输出字段本身会触发渲染报错，正确调用方式如下：

<!-- section内字段调用示例 -->
{% if section.settings.image != blank %}
<img 
  src="{{ section.settings.image | image_url: width: 750 }}"
  alt="{{ section.settings.image.alt | default: '展示图' | escape }}"
  width="750"
  height="auto"
  loading="lazy"
>
{% endif %}