Shopify Liquid paginate 教程：Dawn 集合页分页与性能限制实测
Shopify Liquid paginate 不只是把页码放到商品列表底部。它同时决定每次查询多少条数据、当前页使用哪个 URL 参数，以及筛选条件能否在翻页时继续保留。本文基于 Dawn 16.0.0 的集合页代码做一次完整拆解，并用 Shopify CLI 4.7.1 验证分页大小门禁。
本次只修改本地主题副本，没有上传主题，也没有改动在线商店。基线 Theme Check 检查 156 个文件，得到 Dawn 副本已有的 11 个 warning；加入测试 Section 后，把每页数量从 60 改回 24，新增的 PaginationSize warning 消失，最终仍是原来的 11 个 warning。
Shopify Liquid paginate 解决什么问题
Liquid 的普通 for 循环每页最多迭代 50 次。要遍历更长的可分页数组，应把循环放进 paginate 标签。这样 Shopify 会按页查询数据，并在标签内部提供 paginate 对象。
可分页对象不只有 collection.products，还包括博客文章、搜索结果、客户订单、产品变体，以及部分列表类型的主题设置。对集合页来说，最常见的结构是“分页标签包住商品循环，循环结束后再输出翻页导航”。
Dawn 集合页的实际分页结构
Dawn 16.0.0 在 sections/main-collection-product-grid.liquid 中使用下面这行代码：
{% paginate collection.products by section.settings.products_per_page %}products_per_page 不是写死的数字，而是该 Section 的范围设置。Dawn 给出的范围是 8–36，步进 4，默认值 16。商品循环、筛选组件和分页导航都位于同一个 paginate 作用域内；只有 paginate.pages > 1 时，才会渲染 snippets/pagination.liquid。
如果还没理清 template、section 和 snippet 的职责，可以先看 Shopify Dawn 主题目录结构。集合模板负责装配 Section，商品网格 Section 负责查询与循环，pagination snippet 则专门负责导航标记。
一个可复现的最小分页 Section
为了单独验证 Shopify Liquid paginate，我在 Dawn 副本中增加了一个只用于本地测试的集合页 Section。它每页取 24 个商品，并复用 Dawn 现有的分页 snippet：
<div class="page-width">
{% paginate collection.products by 24 %}
<ul role="list">
{% for product in collection.products %}
<li>{{ product.title | escape }}</li>
{% endfor %}
</ul>
{% if paginate.pages > 1 %}
{% render 'pagination', paginate: paginate %}
{% endif %}
{% endpaginate %}
</div>这里的 paginate 对象只在标签内部可用。把导航挪到 endpaginate 后面，或在 render 时忘记显式传入 paginate，snippet 都拿不到当前页、上一页和下一页数据。
default_pagination 还是自定义 snippet
最快的写法是 {{ paginate | default_pagination }}。它会直接生成上一页、页码和下一页链接，也能通过参数调整前后翻页文字或追加锚点。适合原型和简单主题。
Dawn 没有直接使用这个过滤器，而是遍历 paginate.parts，并读取 paginate.previous、paginate.next 和 paginate.current_page。这样可以控制图标、class、aria-current 和无障碍标签，同时保持与主题样式一致。
自定义导航时不要只拼接 ?page=2。优先使用 part.url、previous.url 和 next.url，因为这些 URL 由 Shopify 生成，更适合与集合筛选、排序和现有查询参数一起工作。
250 是平台上限，不是建议的每页数量
Shopify 当前允许 paginate 的 page_size 在 1–250 之间，但这只是平台边界，不代表集合页应该一次输出 250 张商品卡。Dawn 把可配置范围收在 8–36，默认 16，更符合常见商品网格的图片、DOM 数量和移动端加载成本。
另一个边界是最多分页到数组的第 25,000 项；对超过这个规模的目录，官方建议先通过商品类型、价格、库存等筛选缩小结果，而不是让买家一直翻到极深页码。计数超过 25,000 时也要把 25,001 理解为“多于 25,000”，不是精确总数。
Theme Check 前后实测
平台允许到 250，但项目可以设更严格的性能阈值。我在测试副本的 .theme-check.yml 中把 PaginationSize.max_size 设为 50，再把测试 Section 改成每页 60 条：
PaginationSize:
enabled: true
min_size: 1
max_size: 50运行 shopify theme check 后，新增文件得到一条 PaginationSize warning，提示分页数量必须在 1–50 之间。把 60 改成 24 后再次检查，这条 warning 消失；全主题只剩 11 条与基线相同的既有 warning，测试 Section 本身没有 offense。单独使用 Shopify Liquid 校验器检查该 Section 也通过。
这类对比必须保留基线。否则看到 Theme Check 仍有 warning，很容易把 Dawn 原有问题误判成本次修改引入；反过来，只看命令退出成功，也可能漏掉新出现的性能提示。完整的 Theme Check 使用方法可以继续看 Shopify Theme Check 教程。
page 参数和多个分页列表
普通分页默认使用 page 查询参数，可以通过 paginate.page_param 读取。对主题设置或 metafield 中的 product_list、collection_list、article_list 数组，Shopify 会生成类似 page_a9e329dc 的唯一参数，让同一页面上的多个列表可以独立分页。
如果需要让两个列表独立翻页且不刷新整页，官方建议结合 Section Rendering API。这个范围已经不只是输出几个页码，还要处理请求竞争、加载状态、浏览器历史和无障碍焦点；不要先用一段全局 JavaScript 拦截所有分页链接。
修改 Dawn 分页时的检查清单
- 确认循环和分页导航都在同一组
paginate标签内。 - 使用
paginate.pages > 1避免单页结果输出空导航。 - 优先使用 Shopify 生成的
part.url，不要手工丢掉筛选和排序参数。 - 根据商品卡图片和移动端布局设置合理的每页数量，不把 250 当推荐值。
- 保留 Theme Check 修改前后的结果，区分基线 warning 与新增 offense。
- 在草稿主题中检查第一页、中间页、最后一页、筛选后翻页和返回键。
本次结论
Shopify Liquid paginate 的可靠改法不是把数字尽量调大，而是让查询大小、商品循环、导航 URL 和主题设置保持一致。Dawn 16.0.0 默认每页 16、可调 8–36；这次本地测试把 60 调回 24 后，PaginationSize 新增 warning 被消除，原有基线 warning 数量保持不变。
如果分页代码还要放进新的页面结构，建议先读 Shopify JSON template 实测，再把 Section 加到备用模板中验证。这样能把“分页逻辑是否正确”和“模板是否装配正确”分开排查。
官方资料：Liquid paginate tag、paginate object、default_pagination filter、平台分页限制、PaginationSize、分页限制 Changelog、Dawn v16.0.0 集合页源码、Dawn v16.0.0 分页 snippet（访问日期：2026 年 9 月 9 日；实测环境：Dawn 16.0.0、Shopify CLI 4.7.1）。
