如何调试Squarespace JSON-T应用并解决查询仅返回20条内容问题

这是Squarespace 7.1版本未写入公开文档的破坏性变更，和代码逻辑、CMS后台设置无关：

• 7.0版本中，<squarespace:query>标签未显式指定size参数时，默认拉取目标集合下的全部内容；升级到7.1后，平台给无size参数的查询加了默认返回20条的硬限制，枚举到20条就会自动终止。
• 7.1同时给单次查询设置了100条的硬上限，就算手动给size传大于100的值，单次最多也只能返回100条内容，超过100条的部分必须配合skip参数做分页拉取。

你当前的代码只配置了skip="1"（跳过最新的1条内容），没有声明size参数，刚好触发了20条的默认限制，所以才会出现内容只加载20条、后端数据完整无缺失的情况。

对应的修复方式：

1. 如果播客总条目数不超过100，直接在query标签上增加size参数即可，修改后的标签开头如下：

<squarespace:query collection="podcast" skip="1" size="100">

2. 如果播客总条目超过100，需要手写分页逻辑：第一次查询传skip="0" size="100"，第二次传skip="100" size="100"，以此类推，直到某次查询返回的条目数小于100，就说明已经拉取完所有内容。
   注意：7.1版本中skip参数从0开始计数，当前代码里的skip="1"会跳过最新发布的1条播客，如果不是刻意要排除置顶内容，建议把skip值改成0或者直接移除该参数。

Squarespace官方不提供自定义代码的调试支持，公开文档对JSON-T的逻辑说明也严重缺失，以下是开发者社区长期验证可用的调试手段，按实用度排序：

• 上下文全量打印：在需要调试的代码块最外层加入{.var_dump?}（注意末尾带问号），页面渲染时会直接打印当前节点下所有可用的JSON结构、字段名、对应值，可直接确认目标字段是否存在、值是否符合预期，是效率最高的调试方式。如果要查看整个页面的全量返回数据，把这个标签放在模板最顶部即可。
• 分段注释定位语法错误：JSON-T没有明确的语法报错提示，7.1版本对语法合规性的校验比7.0严格很多，多余空格、未闭合的section标签、不存在的字段过滤器都会直接导致整个查询块渲染中断，且前端控制台不会抛出明确错误。遇到渲染异常时，用{# 注释内容 #}的语法逐段注释代码，每次只放开小范围代码块，逐步缩小范围定位出错的具体代码段，再逐行核对语法即可。
• 原生JSON数据核对：直接在需要调试的页面URL末尾拼接?format=json，就能拿到Squarespace后端返回给该页面的原生JSON数据，所有集合条目、字段名、分页参数都在返回结果里，可以直接和模板里写的字段名一一比对，避免因为7.1版本字段名变更（比如部分旧版的assetUrl字段在7.1中调整为asset.imageUrl）导致的渲染异常。
• 过滤器单独测试：所有JSON-T过滤器（比如代码中用到的|date %B %e, %G），先单独绑定到已知有值的字段上测试，确认输出符合预期再嵌入正式代码。7.1对日期过滤器的格式符做过隐性调整，部分旧格式符会返回空值但不会中断整体渲染，排查问题时很容易被忽略。

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