本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：8月12日的备份/update/9/sosite-plugin-dev/references/02-hooks-catalog.md。
02 · Hooks 目录（全部钩子速查）
钩子机制：Plugin::hook('name', $params) 遍历已启用插件，include 注册的 hook 文件。
hook 文件内可用变量：$params 经 extract(EXTR_SKIP | EXTR_REFS) 注入 + 调用点作用域变量（如 $router、$view）。
单个 hook 抛异常会被 try/catch 捕获，不影响页面继续运行（error_log 记录）。
路径安全：hook 文件必须位于插件目录内（realpath 校验，防穿越），违规直接跳过。
初始化与全局
| Hook | 触发点 | 可用变量/参数 | 典型用途 |
|---|
init_after | app/init.php 插件初始化后 | — | 一次性初始化（注意：建议建表放 activate，懒初始化才放这里） |
controller_view_before | Controller::view() 渲染前 | template（视图名）、data（引用，可改数据） | 注入全局数据、改视图参数 |
路由与导航
| Hook | 触发点 | 可用变量/参数 | 典型用途 |
|---|
route_register | 前台路由注册（index.php，dispatch 前） | $router | 注册前台 GET/POST 路由 |
route_before_dispatch | 路由匹配执行前（index.php） | $router | 路由前拦截/全局处理 |
route_after_dispatch | 路由执行后（index.php，请求收尾） | — | 请求后处理（计数落库等） |
admin_route_register | 后台路由注册 | $router | 注册后台路由（URL 不带 /admin 前缀） |
admin_sidebar_links | 后台侧边栏（扩展组内） | $view（$GLOBALS['__view']） | 输出后台侧边栏入口 <a> |
nav_main_links | 前台主导航栏 | $view | 输出顶部导航链接 |
nav_plugin_links | 前台"应用"下拉 + 左栏 | $view（可 null） | 输出应用入口链接（$view->icon() + 名称） |
nav_user_menu_items | 前台用户下拉菜单（移动端头像菜单，个人中心之后） | $view（$GLOBALS['__view']） | 输出用户菜单入口（我的收藏/审核通知/签到等）；⚠️ 曾因核心无触发点不生效，2026-08-09 已在 app/Views/layouts/main.php 补触发点 |
页面注入
| Hook | 触发点 | 可用变量/参数 | 典型用途 |
|---|
layout_head_end | </head> 前 | $view、$bp（BASE_PATH） | 注入 CSS/JS/元信息（可用 $this->url() 生成路径） |
home_sidebar_bottom | 前台侧边栏"友情链接"区 | — | 侧边栏底部内容（移动/桌面两处都触发） |
announcements_display | 首页/版块页公告区 | — | 输出公告条 |
用户行为
| Hook | 触发点 | 参数 | 典型用途 |
|---|
auth_login_after | 登录成功后 | user_id、username | 登录后联动（积分、日志） |
auth_register_before | 注册校验前 | — | 注册前置校验（如邀请码）；错误传 $GLOBALS['auth_register_error']，非空即拦截 |
auth_register_after | 注册成功后 | user_id、username、email | 注册后联动 |
avatar_upload_after | 头像上传成功后 | user_id、avatar（新文件名）、old_avatar | 头像审核等 |
内容行为（发帖/回帖/编辑）
| Hook | 触发点 | 参数 | 典型用途 |
|---|
thread_create_after | 发新帖成功后 | thread_id、user_id、category_id | 发帖联动 |
post_create_after | 回帖成功后 | post_id、thread_id、user_id | 回帖联动 |
thread_edit_after | 编辑主题保存后 | thread_id、user_id | 编辑联动 |
post_edit_after | 编辑回复保存后 | post_id、thread_id、user_id | 编辑联动 |
附件下载
| Hook | 触发点 | 参数 | 典型用途 |
|---|
attachment_download_before | 附件下载控制器输出文件前（AttachmentController::download） | attachment（attachments 行 + category_id）、user_id（可 null） | 积分下载、付费下载等下载前拦截；约定：插件置 $GLOBALS['attachment_download_error'] 非空字符串即终止下载（403 提示），模仿 auth_register_before 的全局传错方式 |
完整 Hooks 清单（按源码触发点核对，2026-08-09）
| Hook | 触发文件 |
|---|
init_after | app/init.php |
controller_view_before | app/Core/Controller.php |
route_register | app/init.php（插件系统加载时） |
admin_route_register | app/init.php（后台初始化时） |
admin_sidebar_links | app/Views/admin/_sidebar.php |
nav_main_links | app/Views/layouts/main.php |
nav_plugin_links | app/Views/layouts/main.php + app/Views/_components/left_sidebar.php（两处） |
nav_user_menu_items | app/Views/layouts/main.php（用户下拉菜单，2026-08-09 补） |
layout_head_end | app/Views/layouts/main.php |
home_sidebar_bottom | app/Views/_components/right_sidebar.php + mobile_sidebar.php（两处） |
announcements_display | app/Views/home/index.php + app/Views/forum/index.php（两处） |
auth_login_after | app/Controllers/AuthController.php |
auth_register_before | app/Controllers/AuthController.php |
auth_register_after | app/Controllers/AuthController.php |
avatar_upload_after | app/Controllers/ProfileController.php |
thread_create_after | app/Controllers/PostController.php |
post_create_after | app/Controllers/ThreadController.php |
thread_edit_after | app/Controllers/ThreadController.php |
post_edit_after | app/Controllers/PostController.php |
注意事项
- 同一 hook 名多处触发（如
nav_plugin_links 两处）：hook 文件会被 include 两次，输出内容会重复——若需避免，用静态变量守卫或只输出一次的内容放 init_after auth_register_before 传错用全局变量约定：$GLOBALS['auth_register_error'] = '错误信息';- 钩子内
echo 直接输出到响应体；不要 exit/die（会终止整页） - 钩子内如需当前视图对象：
$view = $GLOBALS['__view'] ?? null;（可能为 null，需兜底）
