使用devtools开发R包时，data.table的.()函数找不到错误排查

问题描述 #

在全局环境中直接运行以下函数时可正常执行（系统库存在data.table包，但未通过library()加载，仅用data.table::as.data.table调用）：

sample <- function() {
    df <- data.frame('a' = c(1:10), 'b' = c(1:10))
    dt <- data.table::as.data.table(df)

    return (dt[, .(b)])
}

但将该函数放入用devtools创建的R包后，调用sample::sample()时触发错误：Error in .(b) : could not find function "."

复现步骤 #

1. 创建包目录：

devtools::create('home/development/sample', rstudio = FALSE)

2. 将带文档注释的函数保存至包的R目录下的sample.R文件：

#' Example
#'
#' Where is the problem?
#'
#' @return Column 'b' from a data table.
#'
#' @examples
#' \code{sample()}
#'
#' @export
sample <- function() {
    df <- data.frame('a' = c(1:10), 'b' = c(1:10))
    dt <- data.table::as.data.table(df)

    return (dt[, .(b)])
}

3. 执行文档生成与包加载后调用函数：

devtools::document('home/development/sample')
devtools::load_all('home/development/sample', export_all = FALSE, reset = TRUE)
sample::sample()
# 报错：Error in .(b) : could not find function "." 

问题根源 #

• 核心原因是data.table的.()是替代list()的语法糖，并非全局通用函数，而是data.table包定义的特殊符号。
• 全局环境中，调用dt[, .(b)]时，data.table的[.data.table方法会自动解析.()，此时即使未显式加载data.table，R的作用域机制会在调用[时临时查找data.table包内的定义。
• 但R包有严格的作用域规则：包内代码默认只能访问基础包、已导入的包或显式指定命名空间的函数。由于你的包未导入data.table，也未用data.table::.(b)显式指定命名空间，R无法找到.函数的定义，因此报错。
• 该问题与devtools无关，本质是R包的作用域规则导致，DESCRIPTION文件的依赖配置是关键。

解决方法 #

方法1：显式指定命名空间 #

直接将代码中的.(b)改为data.table::.(b)，明确指定函数来源，无需修改DESCRIPTION：

sample <- function() {
    df <- data.frame('a' = c(1:10), 'b' = c(1:10))
    dt <- data.table::as.data.table(df)

    return (dt[, data.table::.(b)])
}

方法2：导入data.table的.函数 #

1. 在包的DESCRIPTION文件中添加data.table为依赖：

Imports:
    data.table

2. 在函数上方添加roxygen注释（自动更新NAMESPACE）：

#' Example
#'
#' Where is the problem?
#'
#' @return Column 'b' from a data table.
#'
#' @examples
#' \code{sample()}
#'
#' @importFrom data.table .
#' @export
sample <- function() {
    df <- data.frame('a' = c(1:10), 'b' = c(1:10))
    dt <- data.table::as.data.table(df)

    return (dt[, .(b)])
}

3. 重新运行devtools::document()更新包的文档与NAMESPACE。

方法3：导入整个data.table包（仅当包大量使用data.table功能时推荐） #

1. 在DESCRIPTION文件中添加：

Imports:
    data.table

2. 在函数上方添加roxygen注释：

#' Example
#'
#' Where is the problem?
#'
#' @return Column 'b' from a data table.
#'
#' @examples
#' \code{sample()}
#'
#' @import data.table
#' @export
sample <- function() {
    df <- data.frame('a' = c(1:10), 'b' = c(1:10))
    dt <- as.data.table(df)

    return (dt[, .(b)])
}

3. 运行devtools::document()完成配置。

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