R 包构建 + GitHub 部署全流程

这是一个面向新手的 R 包构建与 GitHub 发布入门教程文档。该 Markdown 文档以"从零开始、一步不跳 "为原则，完整记录了创建 R 包骨架、配置 Git、生成文档与示例数据、添加测试、通过 roxygen2 生成帮助文件，以及最终将包发布到 GitHub 并供用户安装使用的全过程。文档严格保留可直接运行的原始代码，每一步都对应明确的操作目的和常见踩坑说明，既可作为第一次构建 R 包的操作指南，也可作为之后重复发布其他包时的标准流程参考。

示例数据"lr_demo.R"保存在：https://github.com/haipizxd-ux/lrdemo2

一、创建 R 包骨架（只需要做一次）

这一步会创建标准 R 包目录结构：DESCRIPTION / NAMESPACE / R/ / man/ / tests/ / ...

r 复制代码

install.packages("usethis")
library(usethis)

# 创建一个新的 R 包项目（生成标准目录结构）
create_package("~/Desktop/lrdemo2") 

# 切换工作目录到包根目录（RStudio 通常会自动切）
setwd("~/Desktop/lrdemo2")

二、配置 Git 用户信息（整台机器只需一次）

只影响你本机 git commit 的署名（不会改 GitHub 账号）。

如果你机器上已经配置过，这步可以跳过。

r 复制代码

# 设置 Git 提交时使用的用户名和邮箱
# 如果你以后在别的包再用 Git，这一步可以跳过
usethis::use_git_config(
  user.name  = "Zhou Xudong",
  user.email = "haipizxd@gmail.com"
)
# 如果没有账号可以在github上免费申请 https://github.com

三、初始化 Git 仓库（每个包一次）

会在包根目录创建 .git/ 并做一次 initial commit。

RStudio 会弹窗让你确认，选 Yup / I agree。

r 复制代码

# 初始化 git 仓库，并进行 initial commit
# 会把当前包骨架作为第一次提交
use_git()
# 选择 Yup / I agree / 同意

四、添加许可证、测试框架、README

这是最推荐的"最低配"三件套：License + testthat + README.Rmd

README.Rmd 之后会 knit 成 README.md，用于 GitHub 展示。

r 复制代码

# 添加 MIT License（会修改 DESCRIPTION 并生成 LICENSE 文件）
use_mit_license("Zhou xudong")

# 添加 testthat 单元测试框架
# 会生成 tests/ 目录
use_testthat()

# 添加 README.Rmd（用于 GitHub 展示）
use_readme_rmd()

五、声明包依赖（非常重要）

只声明依赖，不要在包代码里 library(ggplot2)。

在函数内部用 ggplot2::xxx() 或 requireNamespace("ggplot2")。

r 复制代码

# 声明 ggplot2 是运行时依赖
# 会自动写入 DESCRIPTION 的 Imports
use_package("ggplot2", type = "Imports")

# ⚠️ 注意：
# 这里"只声明依赖"，不要 library(ggplot2)
# 包代码里应使用 ggplot2::xxx 或 requireNamespace()

六、生成"示例数据"（为R包添加附件）

目标：把 example_lr 保存进包的 data/ 目录，供用户 data(example_lr) 直接加载。

注意：use_data() 只能保存"对象名" ，不能直接 name="xxx" 指向别的对象。

r 复制代码

# 调用包函数，生成示例数据
devtools::load_all()
dat <- make_example_data(seed = 42)

# ⚠️ 关键点：
# usethis::use_data() 只能保存"已有对象名"
# 不能 name="example_lr"
example_lr <- dat

# 将 example_lr 保存到 data/ 目录
# 生成 data/example_lr.rda
usethis::use_data(example_lr, overwrite = TRUE)

# ⚠️ 注意：
# use_data() 只能在 Console 里运行
# 不能写进 R/ 目录的函数文件

七、验证示例数据是否能被正确加载

这一步确保你的 data/ 数据"注册成功"。

r 复制代码

# 从当前环境中删除对象
rm(example_lr)

# 从包的数据目录中加载
data(example_lr)

# 查看数据结构
str(example_lr)

# 如果能看到 lr_network / expr_sender / expr_receiver
# 说明数据注册成功

八、创建一个最小测试文件（推荐直接用 usethis）

w之前遇到过 No test files found，就是因为 tests/testthat/ 下没有任何 test-*.R 文件。

用 use_test() 会自动生成标准测试文件，避免这个坑。

r 复制代码

usethis::use_test("lr_demo")
# 它会自动创建"tests/testthat/test-lr_demo.R"
devtools::test()

九、生成帮助文档与 NAMESPACE（必须）

roxygen2 会根据你 R/ 目录里 #' 注释生成：

man/*.Rd 帮助文档

NAMESPACE 导出规则

你提到的包级文档文件 R/lrdemo-package.R，最后一行必须写 "_PACKAGE"（字符串），这是 roxygen2 的包级文档标记。

r 复制代码

# 添加包注释 "R/lrdemo-package.R"
# ⚠️ 注意最后一行：
# 必须是字符串 "_PACKAGE"，不能是变量，这是 roxygen2 的包级文档标记。

# 根据 roxygen2 注释生成：
# - man/*.Rd 帮助文件
# - NAMESPACE 导出规则
devtools::document()

十、检查、构建、安装 R 包

发布前建议至少跑一次 check()，能提前发现 DESCRIPTION、文档、示例、测试的问题。

r 复制代码

# 运行 R CMD check（CRAN 标准）
# 会检查文档、依赖、示例、测试
devtools::check()

# 构建 tar.gz 包（用于发布/分发）
devtools::build()

# 安装当前开发版本到 R library
devtools::install()

十一、检查当前项目状态（信息性，不改任何东西）

这一步用来确认：你现在是不是在包目录、git 是否正常、有哪些文件改了还没提交。

r 复制代码

# 查看当前 R 项目的整体状态
# 包括：Git、R 版本、依赖、是否在包项目中
usethis::proj_sitrep()

# 再次尝试初始化 Git
# 如果 Git 已经初始化，这一步不会重复创建
# 主要用于确认 Git 环境是否正常
usethis::use_git()

# 查看当前 Git 状态（有哪些文件已修改/未提交）
# 等同于在终端里运行 git status
system("git status")

十二、GitHub 认证相关（通常只需要做一次）

usethis::use_github() 需要 GitHub 认证。最常用的是 PAT。

你之前遇到 GitHub API error (401): Bad credentials，基本就是 PAT 没配置好或没重启 R。

r 复制代码

# 在浏览器中创建 GitHub Personal Access Token (PAT)
# 如果你已经创建并配置过，可以跳过
usethis::create_github_token()

# 打开 .Renviron 文件，用于安全保存 PAT
# 只需把 GITHUB_PAT=xxxx 写进去一次即可
usethis::edit_r_environ()

# 做完这一步必须重启 R ！！！

十三、将本地包发布到 GitHub

前提：

已经 use_git() 并有 commit

已配置 PAT 并 重启 R

如果仓库已存在，use_github() 通常会提示已完成或给出对应信息。

r 复制代码

setwd("~/Desktop/lrdemo2")
# 在 GitHub 上创建仓库，并将当前包推送上去
# 前提：Git 已初始化 + PAT 已配置
# 如果仓库已存在，这一步通常会提示已完成
usethis::use_github()

# 覆盖存档：usethis::use_git_remote("origin", url = NULL, overwrite = TRUE)
# 选择: 同意 

# 自动跳转
# https://github.com/haipizxd-ux/lrdemo

十四、用户使用 lrdemo2 包

这里是"用户视角"的最短使用路径：加载 → 生成示例数据 → 计算 → 画图。

r 复制代码

## 1. 加载包
# install.packages("devtools")
devtools::install_github("haipizxd-ux/lrdemo2")
library(lrdemo2)

## 2. 使用包内函数生成示例数据
dat <- make_example_data(seed = 42)

## 看看数据结构是否合理
str(dat)

## 3. 计算 ligand--receptor 活性
lr_res <- score_active_lr(
  expr_sender   = dat$expr_sender,
  expr_receiver = dat$expr_receiver,
  lr_network    = dat$lr_network,
  sender_cutoff = 1,
  receiver_cutoff = 1
)

## 查看结果
head(lr_res)
nrow(lr_res)

## 4. 可视化结果
plot_lr_results(lr_res)