Quarto .qmd转HTML时图片交叉引用无法解析问题求助

问题场景 #

在.qmd文件中插入带ID的图片后，使用@fig-pay_bame_diff进行交叉引用时出现警告Unable to resolve crossref @fig-pay_bame_diff，图片能正常显示但引用失效。

原因 #

Quarto的交叉引用系统不会仅通过#fig-xxx格式的ID识别图引用目标，必须明确标记这是一个可引用的图元素——要么给图片添加图标题属性，要么用图容器包裹内容。

解决方案 #

方案1：添加fig-cap属性（推荐） #

修改图片代码，加上fig-cap（图标题）属性，Quarto会自动识别为可交叉引用的图：

![](images/plt_pay_bame_diff){#fig-pay_bame_diff fig-cap="不同族裔薪资差异对比图"}

If you look at @fig-pay_bame_diff

编译后@fig-pay_bame_diff会自动替换为带跳转链接的图编号（比如“图1”），点击即可定位到图片位置。

方案2：使用图容器 #

如果需要更灵活的图说明格式，可以用块容器包裹图片和标题：

::: {#fig-pay_bame_diff}
![](images/plt_pay_bame_diff)
不同族裔薪资差异对比图
:::

If you look at @fig-pay_bame_diff

容器内的第二行即为图标题，同样能被交叉引用系统识别。

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