1. ext 是什么

ext 是内容和栏目上的扩展字段，以 JSON 字符串形式存储。它用来承载标准字段之外的信息，例如徽标、跳转按钮、附加属性、筛选维度等。

典型场景：

• 列表卡片上显示一个角标（如「推荐」「新版」）
• 详情页底部放一个自定义 CTA 按钮
• 栏目下挂载筛选项（如按地区、按规格过滤）
• 业务特有的附加属性，不想为此改表结构

2. 为什么填了前台不显示

这是最高频的问题，答案几乎总是同一个：模板没有读取它。

ext 只是把数据存下来了，它不会自动渲染。展示与否完全取决于当前主题的模板有没有去读这个字段。所以排查顺序是：

1. 确认数据真的存进去了。后台保存后重新打开，看字段还在不在。外部 API 和 MCP 写入时，ext 必须传合法 JSON 字符串，不是对象。
2. 确认模板读了它。在模板里输出一下，看能不能取到值。字段加进去不等于一定会显示，这两件事是分开的。
3. 确认改的是当前启用主题的模板。改了其他主题目录不会有任何效果。
4. 确认没有被缓存挡住。改完模板前台没反应，先按视图缓存那一套排查。

3. 在模板里怎么用

ext 是字符串，取到之后按 JSON 解析出各个键，再逐个输出。用法要点：

• 先判空再取。不是每条内容都填了 ext，直接取很容易在列表页翻车。
• 键名要稳定。同一个用途在不同栏目里不要换写法，否则模板要写一堆分支。
• 给缺失值兜底。可以用基础函数 default 给个默认值，避免页面出现空白。
• 输出 HTML 要显式声明安全。如果 ext 里存的是 HTML 片段，需要用 safeHTML（或 Str2Html）标记，否则会被转义成纯文本显示出来。

4. 栏目扩展字段还能驱动筛选

栏目级别的 ext 除了展示，还可以用来生成筛选项。系统提供了 ColumnExtFilter 函数，它会根据栏目对象和当前请求，生成一组筛选项供模板渲染。

这让「按扩展属性过滤内容」不需要写死在模板里，配置改了筛选就跟着变。

5. 使用建议

• 先规划再填。ext 是自由格式，一旦各栏目各写一套，后面批量维护会非常痛苦。建议先定一份键名规范。
• 不要用它替代标准字段。标题、摘要、关键词、标签这些有专门字段，放进 ext 会失去内置的检索和排序能力。
• 不要塞大段内容。ext 适合放结构化小数据，正文就该放在正文字段。
• 备份前确认。ext 属于内容数据，会被 safe-site 备份带走；但它引用的图片等附件在 uploads 目录里，需要另外备份。