R包CMD检查工具结果不一致的成因及排查思路

• 检查环境的版本梯度与基础配置不统一
  • R版本覆盖范围不同：多数开发者配置GitHub Actions、Travis这类CI流程时，只会指定自己常用的1-2个稳定版R做检查，不会覆盖全版本梯度；而Rhub这类专门的包检查工具默认会覆盖从最旧的兼容版、当前稳定版到最新开发版R的全量梯度校验，不少在新版R下能正常运行的代码，在旧版R上会因为函数废弃、语法兼容问题直接报错。
  • 环境的干净程度不同：本地检查、CI流程的运行环境往往是长期使用的半干净状态，会残留之前安装的各类R包、系统依赖；而Rhub、官方CRAN检查的运行镜像都是完全干净的全新环境，只会按照包的DESCRIPTION文件声明的依赖列表安装对应组件。如果包的依赖声明有遗漏——比如某个实际被调用的包没写进Imports字段，半干净环境下因为残留了对应包就能跑通，干净镜像里就会直接报找不到依赖的错误。
  • 系统依赖的预装差异：不同工具的运行镜像预装的系统库、编译器版本差异很大，比如部分CI镜像预装了最新版的libcurl、libxml2等编译依赖，而Rhub针对不同Linux发行版的镜像，会使用发行版官方源自带的老版本系统库，甚至完全不预装部分小众编译依赖，就会出现编译环节的报错差异。
• 检查的严格度与运行规则不统一
  • 参数配置差异：本地跑devtools::check()、CI流程的检查往往为了加快运行速度，会主动放宽部分校验规则——比如跳过vignette渲染、把警告级别的条目设为可通过、不开启CRAN标准的全量检查参数；而Rhub、官方Windows开发版检查的默认配置是完全对齐CRAN的强制校验标准，哪怕是提示级别的条目都可能判定为不通过，自然会出现结果差异。
  • 运行权限与沙箱规则差异：CI流程、本地检查的运行权限通常比较宽松，允许测试脚本联网拉取测试数据、随意写文件到系统临时目录；而Rhub的沙箱环境有严格的运行限制，默认禁止联网、限制文件可写路径范围、使用普通用户权限运行，但凡代码或测试用例里有联网拉资源、往受限路径写文件的逻辑，在沙箱里就会失败，在权限宽松的CI里就能正常跑通。
  • 本地化配置差异：不同镜像的时区、文本编码区域设置不同，比如部分CI镜像默认使用UTC时区、英文编码环境，而Rhub会覆盖不同时区、不同语言区域的配置做兼容检查，代码里如果存在硬编码的时间解析、文本编码处理逻辑，就会在特定区域设置下出现解析错误。

• 第一步先定位错位的配置环节
  • 先逐行对齐两边的基础参数：把GitHub Actions运行时使用的R版本、操作系统版本、预装系统依赖列表，和Rhub报错对应节点的配置做对比，先明确是哪组配置不匹配——比如是不是Rhub触发了旧版R下的检查、是不是对应Linux发行版缺失了CI镜像里预装的某个系统库，不要上来就改代码。
  • 精准定位Rhub的报错发生阶段：
    • 如果是安装/编译阶段报错：优先排查缺失的系统依赖、编译器版本兼容问题，比如报错提示找不到对应头文件、动态链接失败，直接根据报错信息补全对应配置即可。
    • 如果是测试运行阶段报错：优先排查沙箱规则差异，比如是不是因为禁止联网导致测试数据拉取失败、是不是文件权限不足导致写操作失败、是不是R版本差异导致内置函数行为变化。
    • 如果是合规检查阶段（即R CMD check流程最后输出的NOTE/WARNING条目）报错：这类问题大多是本地CI为了加快速度主动放开的检查项，比如包体积超标、vignette渲染超时、文档拼写警告等，直接按照Rhub输出的提示逐条整改即可，不需要改动核心代码逻辑。
• 第二步缩小排查范围，减少无效工作
  • 优先找两边检查结果的交集：如果两边在相同R版本、相同操作系统配置下的检查都能通过，那问题一定出在两边配置不一致的环节，不要修改已经在共同环境下验证过的代码逻辑。
  • 针对性匹配报错的专属场景：如果Rhub的报错只在某一个特定的操作系统、R版本组合下出现，直接调整该场景下的兼容逻辑即可，不需要做全局修改。
  • 直接复用Rhub输出的完整日志栈：日志里的报错行号、函数调用栈是最直接的定位线索，不要在本地盲目复现问题——很多时候为了复现问题手动安装一堆依赖，反而会把本地环境搞的更混乱，顺着日志栈定位代码位置效率更高。

内容的提问来源于stack exchange，提问作者A.Fischer