如何在bookdown::pdf_document2中为手动插入的图片添加图注？

嗨，我之前也碰到过这个问题——knitr::include_graphics配合fig.subcap在bookdown的pdf输出里编译失败，其实是没摸准bookdown处理子图注的正确姿势，下面给你一步步讲怎么搞定：

1. 代码块的核心选项必须配全 #

bookdown的fig.subcap不能单独用，得和几个关键选项搭配才行。你需要在代码块里同时指定：

• fig.cap：整个图片组的总标题（必填，因为bookdown的子图注依赖总标题来关联）
• fig.subcap：一个字符串向量，对应每个子图的标注
• fig.ncol：可选，控制子图的列数，让排版更整齐
• echo=FALSE：避免显示插入图片的代码

示例代码块长这样：

```{r knit-logos, echo=FALSE, fig.cap="这是三个knit图标的总标题", fig.subcap=c("第一个图标", "第二个图标", "第三个图标"), fig.ncol=3}
knitr::include_graphics(rep("images/knit-logo.png", 3))

## 2. 确认输出格式是bookdown专属的pdf
一定要确保你的文档输出设置是`bookdown::pdf_document2`，而不是普通的`rmarkdown::pdf_document`——只有前者才支持子图注的渲染逻辑。比如在`_output.yml`里这么写：
```yaml
output:
  bookdown::pdf_document2:
    toc: true
    number_sections: true

3. 踩过的坑给你避一避 #

• 路径别错：检查images/knit-logo.png的相对路径是否正确，最好把图片放在项目根目录的images文件夹里，避免绝对路径的麻烦。
• 更新包：旧版本的bookdown或knitr可能有子图注的bug，先跑update.packages(c("bookdown", "knitr"))更到最新版试试。
• 别混搭grid.arrange：include_graphics配合代码块的fig.ncol已经能搞定排列，再加grid.arrange会打乱bookdown的图注关联逻辑，直接失效。

如果需要更灵活的排版（比如不同子图大小、复杂布局），可以用patchwork包把图片转成ggplot对象再组合，这样也能完美适配fig.subcap，示例：

```{r custom-layout, echo=FALSE, fig.cap="自定义布局的图标组", fig.subcap=c("左图", "中图", "右图")}
library(patchwork)
# 把图片转成ggplot对象
img = ggplot() + 
  annotation_custom(grid::rasterGrob(png::readPNG("images/knit-logo.png"))) + 
  theme_void()

# 用patchwork自由组合，比如左图占2列，右两个各占1列
img + img + img + plot_layout(ncol=4, widths=c(2,1,1))

这样编译出来的pdf里，子图注就会正常显示啦！

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