💡（.onLoad、.onAttach、.onUnload、.onDetach）
在 R 包开发中，有一些特殊的生命周期钩子函数（hook functions） ，它们会在包被加载、附加、卸载或分离等不同阶段自动触发，用于执行初始化或清理操作。
本文总结了所有这些函数的触发时机、典型用途和区别，并提供了完整的示例代码。
🧩 一、加载（Loading）阶段的钩子函数
| 函数 | 触发时机 | 说明 |
|---|---|---|
.onLoad(libname, pkgname) |
当包被加载到内存 （library.dynam 调用后）但尚未附加到搜索路径 时触发。即执行 library(pkg) 或 require(pkg) 的早期阶段。 |
初始化内部数据结构、加载动态库、设置选项、注册 S3/S4 方法、Rcpp 模块等。 |
.onAttach(libname, pkgname) |
当包被附加到搜索路径 （即 search() 列表中出现）时触发。紧接在 .onLoad() 之后。 |
打印启动信息（如 packageStartupMessage()）、加载默认数据、设置环境变量等。 |
🧠 区别总结：
-
.onLoad()→ 包刚被"加载"进内存（对内部可用） -
.onAttach()→ 包被"附加"到搜索路径（对用户可用）
.onLoad <- function(libname, pkgname) {
packageStartupMessage("Loading internal structures...")
}
.onAttach <- function(libname, pkgname) {
packageStartupMessage("Welcome to MyPackage v1.0!")
}
🧩 二、卸载（Unloading）阶段的钩子函数
| 函数 | 触发时机 | 说明 |
|---|---|---|
.onUnload(libpath) |
当包被从内存中卸载 （例如 unloadNamespace("pkg") 或 R 退出时自动卸载）时触发。 |
清理内存、卸载动态库、关闭连接、注销方法等。 |
.onUnload <- function(libpath) {
library.dynam.unload("MyPackage", libpath)
}
🧩 三、分离（Detaching）阶段的钩子函数
| 函数 | 触发时机 | 说明 |
|---|---|---|
.onDetach(libpath) |
当包被从搜索路径中分离 （detach("package:pkg", unload = FALSE)）时触发。 |
撤销搜索路径设置、关闭临时连接、提示用户等。 |
🧠 注意：
-
.onDetach()不会卸载命名空间（包仍在内存中）； -
.onUnload()才是命名空间卸载； -
通常
.onDetach()→.onUnload()只有在unload = TRUE时才连续触发。
🧩 四、会话钩子函数（与包生命周期无关，但常用）
| 函数 | 触发时机 | 说明 |
|---|---|---|
.Last.lib(libpath) |
历史遗留函数（旧式 .onUnload），现已不推荐。 |
与 .onUnload 类似。 |
.First.lib(libname, pkgname) |
历史遗留函数（旧式 .onAttach），现已不推荐。 |
与 .onAttach 类似。 |
.onLoad_all() / .onAttach_all() |
在开发工具（如 devtools::load_all()）中模拟的内部钩子。 |
用于开发环境自动加载逻辑。 |
.Last() |
当 R 会话结束时调用。 | 保存状态、关闭连接、打印退出信息等。 |
🧠 五、生命周期层级关系
加载包时：
→ .onLoad()
→ .onAttach()
分离包时：
→ .onDetach()
→ .onUnload()
💡 六、完整示例
.onLoad <- function(libname, pkgname) {
library.dynam("MyPkg", pkgname, libname)
options(mypkg.debug = TRUE)
}
.onAttach <- function(libname, pkgname) {
packageStartupMessage("MyPkg v1.0 loaded successfully!")
}
.onDetach <- function(libpath) {
message("Detaching MyPkg...")
}
.onUnload <- function(libpath) {
library.dynam.unload("MyPkg", libpath)
}
🚦 七、小结表
| 阶段 | 钩子函数 | 是否推荐使用 | 常见作用 |
|---|---|---|---|
| 加载命名空间 | .onLoad |
✅ | 注册方法、动态库、内部对象 |
| 附加包 | .onAttach |
✅ | 打印消息、设置环境变量 |
| 分离包 | .onDetach |
✅ | 清理设置、提示用户 |
| 卸载命名空间 | .onUnload |
✅ | 卸载动态库、释放资源 |
| 历史版本 | .First.lib / .Last.lib |
❌ | 仅兼容旧包 |