devtools::install_local构建vignette时跨文档变量共享问题咨询

API 探路者

2026-9-29

问题原因

默认情况下，使用devtools::install_local或者R CMD build构建包的vignettes时，所有vignette会在同一个R会话的全局环境中，按照文件名字典顺序依次渲染。前一个vignette运行时创建的变量会保留在全局环境中，后续渲染的vignette就可以直接访问这些变量，所以你按aaa_1在前、aaa_2在后的顺序构建时不会报错，反过来就会因为找不到变量a失败。
这不是vignette的变量本身是全局变量，是本地默认的构建流程共享环境导致的变量泄露。如果你的包提交到CRAN，CRAN的构建系统默认会为每个vignette启动独立进程渲染，不会出现这个问题。

避免跨vignette变量泄露的方法

每个vignette设置独立运行环境：在每个vignette的开头添加一个setup代码块，指定当前vignette的所有代码都运行在独立的私有环境中，不会读写全局环境的变量，该方法最稳妥，不会影响其他构建流程：
```
```{r setup, include=FALSE}
# 所有代码块使用独立环境，避免跨vignette变量泄露
knitr::opts_chunk$set(envir = new.env())
```
构建时强制每个vignette单独运行：设置环境变量R_BUILD_VIGNETTES_SEQUENTIAL=1，告诉R构建工具每个vignette都启动独立的R进程渲染，完全隔离环境，你可以在运行安装命令前先执行：
```
Sys.setenv(R_BUILD_VIGNETTES_SEQUENTIAL = "1")
devtools::install_local("package", build_vignette = TRUE)
```
主动清理环境：如果不需要保留构建环境的其他内容，可以在每个vignette的最开头添加代码清空当前环境的变量，注意该方法会删除当前环境所有已存在的变量，不建议在有特殊构建配置的场景下使用：
```
rm(list = ls(all.names = TRUE))
```