Shopify Online Store 2.0参数变化时Liquid区块缓存机制问询

问题场景 #

我正在开发Shopify Online Store 2.0主题，遇到疑似缓存导致的区块输出不一致问题。我有一个根据URL查询参数条件渲染的区块，代码如下：

{% if request.params.view_mode == 'compact' %}
  <!-- compact layout -->
{% else %}
  <!-- default layout -->
{% endif %}

首次加载带?view_mode=compact的页面时，区块渲染正常；但导航离开后返回无该参数的页面时，区块偶尔仍显示紧凑布局，直到强制刷新。此现象表明存在区块或模板级缓存。

疑问 #

1. Shopify边缘缓存层是否不按查询参数区分，直接缓存区块的完整HTML输出？
2. Shopify Online Store 2.0页面的缓存键包含哪些请求属性？
3. 是否有文档化方法可阻止基于URL参数的Liquid输出缓存？

注：未使用任何外部CDN或自定义反向代理，此为Shopify原生行为，希望明确当Liquid逻辑依赖request.params时，Shopify如何判定缓存差异。

解答 #

1. 边缘缓存对查询参数的处理 #

Shopify的边缘缓存默认不会将所有查询参数纳入缓存区分逻辑。只有Shopify官方定义的特殊查询参数（比如variant、locale这类和核心功能强相关的参数）会被自动作为缓存键的一部分。像你自定义的view_mode这类参数，默认不会触发缓存区分，所以带参数和不带参数的页面可能会共享同一缓存副本，导致渲染异常。

2. 缓存键包含的请求属性 #

Shopify Online Store 2.0的页面缓存键核心包含以下属性：

• 请求的完整路径（不含自定义查询参数）
• 店铺的域名与语言环境（locale参数）
• 设备类型（移动端/桌面端）
• 已登录用户的身份标识（仅针对个性化内容，比如顾客专属价格）
• 部分官方特殊查询参数（如variant、preview_theme_id）

自定义查询参数默认不会被加入缓存键，这也是你遇到问题的核心原因。

3. 阻止基于URL参数的缓存方法 #

有两种官方支持的方式处理这类依赖自定义查询参数的渲染逻辑：

• 使用{% render %}标签的缓存参数：在渲染区块时显式禁用缓存，或者指定缓存键包含自定义参数。例如：

  {% render 'your-block', cache: false %}
  

  或者更精细地控制缓存键：

  {% render 'your-block', cache: true, cache_key: request.params.view_mode %}
  

  这样缓存会根据view_mode的值区分不同副本。
• 切换渲染方式：如果之前使用section标签渲染区块，建议改用render标签——section的默认缓存逻辑更固化，render能更灵活地控制缓存行为。

内容的提问来源于stack exchange，提问作者user32382293