如何解决R中运行devtools::build_vignettes()时的“System command error”？

问题场景 #

我正在开发名为PhosMap的R包，包根目录下的./vignettes文件夹里已经有写好的.Rmd文件，想要自动把它转成.html和.pdf并存到./inst/doc目录，于是执行了这段代码：

library("devtools")
build_vignettes()

结果连续两次抛出系统命令错误：

Building PhosMap vignettes
Error in (function (command = NULL, args = character(), error_on_status = TRUE, : System command error
Error in (function (command = NULL, args = character(), error_on_status = TRUE, : System command error

我的R版本是3.6.0。

排查与解决步骤 #

针对R 3.6.0环境下的这个问题，我整理了几个实用的排查方向，你可以逐一尝试：

1. 确认LaTeX环境是否安装完整

生成PDF文档必须依赖LaTeX，R 3.6.0搭配TinyTeX（轻量版LaTeX，专为R用户优化）是最省心的选择。如果还没安装，直接运行：

install.packages("tinytex")
tinytex::install_tinytex()

安装完成后重启R，再尝试执行build_vignettes()。

2. 检查devtools版本是否适配R 3.6.0

R 3.6.0对应的devtools稳定版本是2.2.1，版本不匹配很容易引发兼容性问题。先查看当前版本：

packageVersion("devtools")

如果不是2.2.1，卸载后重装适配版本：

install.packages("devtools", version = "2.2.1")

3. 核对vignette的YAML头部配置

你的.Rmd文件必须包含正确的vignette标识，否则devtools无法识别它是包的vignette文档。确保YAML头部类似如下格式：

---
title: "PhosMap使用指南"
author: "你的名字"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
  rmarkdown::pdf_document:
    toc: true
vignette: >
  %\VignetteIndexEntry{PhosMap使用指南}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

注意vignette块里三个以%开头的配置项，一个都不能少。

4. 分步构建定位具体错误

如果还是报错，别直接用build_vignettes()，手动分步渲染文档，这样能看到更详细的错误信息：

# 先渲染HTML文档
rmarkdown::render("vignettes/你的文档名.Rmd", output_format = "html_vignette", output_dir = "inst/doc")
# 再渲染PDF文档
rmarkdown::render("vignettes/你的文档名.Rmd", output_format = "pdf_document", output_dir = "inst/doc")

比如PDF渲染失败时，可能会提示缺少某个LaTeX包，或者R代码存在报错，这样就能精准定位解决。

5. 检查目录读写权限

如果是Windows系统，确保RStudio以管理员身份运行，避免因权限不足无法写入./inst/doc目录；如果是Linux/macOS，给目录添加读写权限：

chmod -R 755 ./inst/doc

内容的提问来源于stack exchange，提问作者X.Wei