R中使用pkgdown编织vignette时外部图片无法显示的求助

核心问题定位 #

你的情况是预生成的外部图片在pkgdown构建的vignette中无法加载，本质是图片路径的解析逻辑在pkgdown构建流程中与本地markdown预览不一致，加上GitHub Actions环境的路径上下文差异，导致路径失效。

针对性解决步骤 #

1. 规范图片存放路径与引用方式 #

pkgdown对vignette中外部资源的路径解析有特定规则，推荐把预生成的图片放在vignettes/images目录（没有就新建），然后在vignette里用相对路径引用：

![](images/elev_rivers.png)

别用man/figures，这个目录是给包函数帮助文档的图片设计的，pkgdown处理vignette时不会默认检索这个路径。

2. 配置pkgdown资源路径（可选但保险） #

如果上面的路径还是不生效，在包根目录的_pkgdown.yml里加以下配置，明确指定vignette的资源目录：

articles:
  assets: vignettes/images

这样pkgdown构建时会自动把vignettes/images下的文件复制到文档输出目录的对应位置，确保路径能匹配上。

3. GitHub Actions环境额外检查 #

• 确保预生成的图片已经提交到GitHub仓库，别在.gitignore里忽略vignettes/images目录
• GitHub Actions的构建脚本里不用额外处理图片，路径配置对了，pkgdown会自动处理资源复制

4. 本地构建验证 #

本地构建前先清理缓存，避免旧路径干扰：

pkgdown::clean_site()
pkgdown::build_articles()

然后去生成的docs/articles/目录下看看，有没有images文件夹且包含目标图片，确认路径对应。

关键注意事项 #

因为你的图片依赖GRASS GIS没法在构建时生成，必须保证预生成的图片：

• 是PNG/JPG这类web兼容格式
• 文件名和路径里别带中文、空格或特殊字符
• 已经正确提交到仓库，本地和远程的文件完全一致

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