迅睿CMS缩略图标签全场景调用实操指南 附常见踩坑排查方案

一、前置配置校验

所有调用操作前需先确认基础配置正常，避免后续无效调试：

• 适用版本：迅睿CMS V4/V5正式版，老版本需先升级到官方稳定版
• 必须开启自动生成开关：进入后台→内容→附件设置→缩略图配置，勾选【自动生成内容缩略图】，保存配置
• 权限校验：站点根目录下runtime/thumb文件夹权限设置为755，确保服务器可写入生成的缩略图文件

二、单页场景缩略图调用

适用于内容详情页、自定义单页等单个内容的缩略图展示场景：

2.1 模块详情页调用

文章、产品等模块详情页直接调取当前内容的缩略图字段，可直接复制以下代码：

``` ```

2.2 全局单页调用

首页、关于我们等独立单页的缩略图调用，代码如下：

``` ```

三、列表页批量缩略图调用

适用于文章列表、产品列表等循环输出多个内容的场景，循环体内固定使用$t变量，不可用$field，完整可复制代码如下：

``` {list action=module module=news num=10}

{$t.title}

{$t.description}

{/list} ```

四、自定义尺寸缩略图调用

需要不同尺寸的缩略图时使用官方内置dr_thumb函数，函数参数规则：dr_thumb(原图地址, 宽度, 高度, 裁剪模式)

裁剪模式参数说明：1=居中裁剪（常用）、2=等比缩放不裁剪、3=拉伸填满

可直接复制以下代码适配不同场景：

``` ```

如果你的站点配置了第三方OSS存储（七牛云、阿里云OSS、腾讯云COS），dr_thumb函数会自动适配对应平台的缩略图处理规则，无需额外修改代码。注意：如果原图尺寸小于你设置的裁剪尺寸，会直接返回原图不会放大。

五、无缩略图兜底方案

用户未上传缩略图时，可通过两种方式配置兜底默认图：

5.1 全局默认缩略图

进入后台→内容→附件设置→缩略图配置，上传默认缩略图后保存，所有未上传缩略图的内容调用thumb字段时，会自动返回该默认图地址，全局生效无需改代码。

5.2 单场景自定义默认图

不同栏目需要不同默认图时，可通过判断语句实现，可直接复制以下代码：

``` {if $t.thumb} {else} {/if} ```

其中{THEME_PATH}为当前模板目录的系统变量，替换主题时无需修改路径。

六、常见问题排查

6.1 调用缩略图返回空

• 检查后台缩略图自动生成开关是否开启
• 确认对应内容是否已上传缩略图，编辑内容页查看缩略图字段是否有值
• 检查变量是否写对：详情页用$field、列表循环用$t、单页用$page
• 确认runtime/thumb目录有写入权限

6.2 自定义尺寸缩略图不生效

• 检查dr_thumb函数参数顺序是否正确，裁剪模式参数是否为1
• 删除runtime/thumb目录下的对应旧缩略图，重新访问生成新文件
• 确认原图尺寸大于你设置的裁剪尺寸，小于时会直接返回原图

6.3 需要生成绝对路径的缩略图

对接小程序、APP等需要绝对路径的场景，用dr_http_url函数包裹即可，代码如下：

``` ```

多站点场景需进入后台→站点管理→对应站点设置，勾选【附件URL使用绝对地址】，避免跨站点调用路径错误。

6.4 第三方OSS存储下缩略图不生效

• 检查对应OSS平台的缩略图处理功能是否已开启
• 确认OSS的访问权限为公共读，避免私有文件无法访问
• 可直接拼接OSS平台自带的缩略图处理参数，无需使用dr_thumb函数