Quarto Book模板中跨qmd文件传递数据的最佳实践

Quarto Book默认给每个章节qmd分配独立的knitr运行环境，所以前序章节创建的对象不会自动传递到后续章节，要避免重复查询数据库，按优先级选以下方案即可：

方案1：全局预处理脚本+本地缓存（生产环境最优解） #

这是可维护性、渲染速度、容错率最高的方案，完全不依赖章节执行顺序。

1. 在项目根目录新建scripts/文件夹，创建data_fetch.R存放所有公共数据读取、清洗逻辑，同时加缓存判断，避免每次渲染都重复连库查询：

# scripts/data_fetch.R
library(DBI)
library(qs)
# 定义缓存路径
cache_file <- "_cache/public_dataset.qs"
# 缓存不存在时查数据库
if (!file.exists(cache_file)) {
  # 建立数据库连接
  con <- dbConnect(
    # 填写对应数据库驱动连接参数，比如RPostgres、RMariaDB等配置
  )
  # 读取需要的公共数据集
  sales_df <- dbGetQuery(con, "SELECT * FROM sales WHERE report_year >= 2022")
  user_df <- dbGetQuery(con, "SELECT * FROM active_users")
  # 断开连接
  dbDisconnect(con)
  # 数据清洗逻辑
  sales_df <- sales_df[!is.na(sales_df$order_amount), ]
  # 把处理好的数据存本地缓存
  if (!dir.exists("_cache")) dir.create("_cache")
  qsave(
    list(sales_df = sales_df, user_df = user_df),
    cache_file
  )
}
# 直接从缓存读数据加载到全局环境
loaded_data <- qread(cache_file)
list2env(loaded_data, envir = .GlobalEnv)

2. 修改_quarto.yml配置，让所有章节渲染前自动运行该脚本，不需要在每个qmd里手动写加载逻辑：

project:
  type: book
  execute:
    freeze: auto # 开启渲染冻结，没改动的章节不会重复跑代码
execute:
  before-chapter: scripts/data_fetch.R # 每个章节渲染前自动加载公共数据

这个方案的优势：

• 数据逻辑和章节内容完全分离，修改查询规则不需要改动任何章节文件
• 第一次查完库之后，后续渲染直接读本地缓存，大样本量下渲染速度能提升数倍
• 不管是全本渲染还是单独渲染某一个章节，都不会出现对象不存在的报错
• 不会出现全局变量污染的问题

方案2：开启全局共享运行环境（小型项目快速实现） #

如果项目体量小、章节少，不想单独拆分脚本，可以直接修改配置关闭章节环境隔离，让所有章节共用同一个R全局进程：

project:
  type: book
execute:
  freeze: auto
knitr:
  opts_chunk:
    envir: .GlobalEnv # 所有代码块都在全局环境运行，对象互通

⚠️ 该方案有明显缺陷，仅适合临时小项目使用：

• 必须严格按照chapters配置里的章节顺序写代码，一旦调整章节顺序，或者单独渲染中间/末尾章节，会因为前序章节没运行直接报对象不存在的错误
• 不同章节里的同名变量会互相覆盖，出现问题时调试成本很高
• 临时创建的冗余变量会一直占用内存，大项目下容易出现内存不足的问题

方案3：按需加载公共脚本（多数据源场景适用） #

如果不同章节用的数据源差异很大，不需要全局加载所有公共数据，可以把不同数据源的读取逻辑分别存在独立R脚本里，在需要用到对应数据的章节开头手动加载：

# 在需要用到销售数据的qmd章节第一个代码块添加
source("scripts/fetch_sales_data.R")

这个方案灵活度最高，不会加载多余数据，但要记得在需要数据的章节手动加source代码，漏写就会报错。

避坑提示 #

• 不要把数据读取逻辑直接写在index.qmd等靠前章节里靠全局环境传值，只要调整章节顺序、单独渲染后续章节就会失效，可维护性极差
• 数据库连接句柄不要跨环境传递，连接属于临时资源，跨进程会直接失效，查完数据及时断开即可，不要把连接对象存入缓存
• 大体积数据集优先用qs包的qsave/qread做序列化，比R原生的saveRDS/readRDS速度快3-10倍，压缩率也更高

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