RStudio渲染Quarto文档时出现add_html_caption()参数错误

问题现象 #

仅特定Quarto文档渲染时触发以下错误，单独运行文档内所有代码正常，其他Quarto文档渲染无异常，已重启R：

Error in `add_html_caption()`:
! unused argument (xfun::grep_sub("^[^<]*<[^>]+aria-labelledby[ ]*=[ ]*\"([^\"]+)\".*$", "\\1", x))
Backtrace:
  1. global .main()
  2. execute(...)
  3. rmarkdown::render(...)
  4. knitr::knit(knit_input, knit_output, envir = envir, quiet = quiet)
  5. knitr:::process_file(text, output)
     ...
 14. sew(res, options)
 15. knitr:::sew.list(x, options, ...)
 16. base::lapply(x, sew, options, ...)
 17. FUN(X[[i]], ...)
 18. knitr:::sew.knit_asis(x, options, ...)
Execution halted

解决方案 #

• 排查文档内的图片/表格标题
  错误源于HTML标题处理逻辑，优先检查文档中所有图片、表格的标题设置：

  • 逐段注释图片/表格代码，定位触发错误的元素
  • 确保使用Quarto标准语法定义标题，例如图片：![描述](路径){#fig-id fig.cap="图片标题"}，表格：| 列1 | 列2 |{#tab-id tab.cap="表格标题"}，避免在标题中嵌入未闭合的HTML标签或自定义aria-labelledby属性。

• 更新knitr与rmarkdown版本
  版本不匹配可能导致函数参数定义不一致：

  • 运行packageVersion("knitr")和packageVersion("rmarkdown")查看当前版本
  • 执行install.packages(c("knitr", "rmarkdown"))更新到最新稳定版，重启R后重试渲染。

• 禁用或清除knitr缓存
  特定文档的缓存文件损坏可能引发异常：

  • 在文档YAML头部添加临时禁用缓存的配置：

    ---
    knit:
      cache: false
    ---
    

  • 或手动删除文档目录下的_cache文件夹，再重新渲染。

• 检查自定义HTML输出代码
  若文档中使用了asis_output()或手动生成HTML内容，需确认是否错误传递了add_html_caption()不支持的参数，排查所有自定义输出代码段的语法逻辑。

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