用途:扩展 Kamal 部署流程,在部署的特定节点运行自定义脚本,实现预检、构建门禁、部署通知、负载均衡摘除等操作。
主要能力:钩子默认位于 .kamal/hooks 文件夹,文件名必须与钩子名完全一致且无扩展名(如 pre-deploy,而非 pre-deploy.sh)。可用钩子包括 docker-setup、pre-connect、pre-build、pre-deploy、post-deploy、pre-app-boot、post-app-boot、pre-proxy-reboot、post-proxy-reboot。脚本返回非零退出码会中止命令,因此 pre-deploy 或 pre-build 可用来拦截部署。Kamal 会向每个钩子传入 KAMAL_* 环境变量,如 KAMAL_VERSION、KAMAL_PERFORMER、KAMAL_HOSTS、KAMAL_COMMAND、KAMAL_DESTINATION、KAMAL_ROLE 等;post-deploy 额外提供 KAMAL_RUNTIME(部署总秒数)。
使用方式:运行 kamal init 生成示例脚本;创建钩子文件后执行 chmod +x .kamal/hooks/pre-deploy 使其可执行;在脚本中读取 KAMAL_* 变量;正常执行 kamal deploy 即自动触发。可用 --skip-hooks(-H)跳过全部钩子。在 config/deploy.yml 中通过 hooks_path 自定义钩子目录,通过 hooks_output 设置 :quiet 或 :verbose 控制输出(可全局或按钩子设置,CLI 的 -v、-q 会覆盖)。
适用场景:部署前检查未提交改动或 CI 状态、部署后发送通知或向 APM 注册版本、重启代理前从外部负载均衡摘除服务器等。
限制:钩子文件名不能带扩展名;非零退出码会中止命令;失败钩子的输出始终显示在错误信息中,不受 hooks_output 影响。