企业官网建设流程全解析

• 开发工具
• 代码评审
• CLI
• AI 应用

Hunk 是一款面向 Agent 编码工作流的 review-first 终端 diff 查看器，支持在 macOS、Linux 与 Windows 上运行。本文以官方安装文档为核心，系统讲解五种安装途径的适用场景、参数用法、版本更新机制与安装验证方法，并结合仓库源码说明校验、冲突检测与更新分发背后的实现原理，帮助读者在任何平台上快速、安全地完成 Hunk 的部署与日常升级。

平台支持与安装方式总览

Hunk 官方支持 macOS、Linux 与 Windows 三种操作系统。不同平台的推荐安装方式如下：

其中 install script 是 macOS 与 Linux 上的默认安装方式，Windows 用户则需要通过 npm 或 mise 安装。从源码结构看，这些方式大体可分为两类：install script、Homebrew、mise 与 Nix 提供的都是自包含二进制（不依赖 Node.js），而 npm 安装则必须满足 Node.js 22+ 的运行时要求（见 packages/hunk/package.json 中"engines": { "node": ">=22" }声明）。无论选择哪种方式，Git 都是推荐具备的前置条件，因为最常见的 review 工作流都基于 Git 工作树展开。

使用官方 install script 安装（默认方式）

在 macOS 与 Linux 上，默认安装脚本会为当前机器下载预编译二进制：

curl -fsSL https://hunk.dev/install.sh | sh hunk --version

脚本执行后将二进制安装到~/.hunk/bin/hunk，并把仓库内置的 agent skills 放在二进制同侧（~/.hunk/skills，这也是hunk skill path命令查找的位置），同时将~/.hunk/bin追加到 shell 启动文件中以加入PATH。安装完成后需要重启 shell（或在新终端中运行export PATH="$HOME/.hunk/bin:$PATH"）才能直接使用hunk命令。

校验机制：SHA256SUMS 与条件性跳过

当某个 release 发布时附带SHA256SUMS文件，且机器上存在sha256sum（Linux/macOS 常用）或shasum（macOS 自带）时，脚本会在安装前校验下载归档的校验和；若校验工具缺失或该 release 未发布校验文件，脚本会给出警告后继续安装。这一逻辑在 install.sh 中有明确实现：脚本先尝试下载SHA256SUMS，随后按sha256sum→shasum -a 256的顺序选择校验工具，并仅在找到对应归档条目时执行-c校验，否则警告 "the archive checksum was not verified" 而不会中断安装。

安装脚本支持的配置项

脚本接受以下设置（来自官方文档表格，并补充了 install.sh 中的解析细节）：

常见用法组合

# 安装指定版本（0.19.0），位置参数写法 curl -fsSL https://hunk.dev/install.sh | sh -s -- 0.19.0 # 不修改 shell 启动文件 curl -fsSL https://hunk.dev/install.sh | sh -s -- --no-modify-path # 允许与已有安装共存 curl -fsSL https://hunk.dev/install.sh | sh -s -- --force # 通过环境变量指定版本 curl -fsSL https://hunk.dev/install.sh | HUNK_VERSION=0.19.0 sh

冲突安装检测：默认拒绝多副本

默认情况下，安装器会拒绝创建第二个 Hunk 安装：它会逐一列出发现的冲突路径、版本与 PATH 优先级，以及移除该安装的对应命令，随后提示用户先移除这些安装，只有在你确实需要管理多个副本时才应使用--force。从 install.sh 源码可以看到，check_competing_installs会扫描 PATH 上的每一个hunk可执行文件，还会额外 glob~/.nvm/versions/node/*/bin/hunk与 mise 的~/.local/share/mise/installs/hunk/*/hunk（处理 nvm 全局安装与未激活版本），并通过 install.sh 的competing_install_channel识别归属方——npm、Homebrew、mise、Bun、pnpm 等——再给出精确的卸载命令（如npm uninstall -g hunkdiff、mise uninstall hunk、bun remove --global hunkdiff）。

自定义目录与后续更新

在 Hunk 0.20 及更新版本上，hunk update可以原地刷新默认安装。但使用HUNK_INSTALL_DIR重定向的安装无法在后续被自动识别（该环境变量在 shell 退出后即消失），因此这类安装的升级方式是带着相同的HUNK_INSTALL_DIR重新运行脚本——安装器在自定义目录安装结束时也会打印此提醒。对应逻辑可见 install.sh 中的 "hunk update cannot auto-detect this custom install directory" 提示。

release 发现的隐私边界

对于 curl 管理的安装，默认的 install script 版本解析、启动时的自动更新检查、hunk update --check与hunk update都会经由 Hunk 的 release 端点（https://updates.hunk.dev/v1/curl/latest）。自动检查每个用户配置文件每 4 小时最多执行一次，多进程并发时可能出现偶发重复，而显式 update 命令与安装器执行始终立即生效。端点仅记录聚合的请求来源与当前版本字段，Hunk 不发送安装 ID、仓库、主机名、cookie 或请求体；HUNK_DISABLE_ANALYTICS=1与DO_NOT_TRACK=1会使 release 发现直连 GitHub，任何端点故障也会回退到 GitHub。这一机制在 install.sh 的fetch_release_proxy中实现：请求会携带X-Hunk-Request-Source: install与可选的X-Hunk-Current-Version头，并用 5 秒超时保证代理故障时快速让位于 GitHub 直连回退。

通过 npm 安装

发布到 npm 的包名为hunkdiff，全局安装即可：

npm install --global hunkdiff hunk --version

该包同时暴露hunk与hunkdiff两个命令（见 packages/hunk/package.json 中"bin": { "hunk": "./bin/hunk.cjs", "hunkdiff": "./bin/hunk.cjs" }），文档统一使用hunk。npm 安装需要 Node.js 22 或更新版本；bun与pnpm的全局安装同样受支持（hunk update会通过 installSource.ts 的detectNpmClient自动识别实际写入全局安装的客户端，避免用错误客户端重装导致旧二进制仍抢占 PATH）。

通过 Homebrew 安装

macOS 与 Linux 用户可以直接从 Homebrew core 安装：

brew install hunk hunk --version

如果此前使用过旧的modem-dev/tapformula，请先卸载再安装：

brew uninstall modem-dev/tap/hunk brew install hunk

通过 mise 安装

mise 以短名hunk（别名hunkdiff）识别 Hunk，并在 macOS、Linux、Windows 上安装预编译二进制：

mise use -g hunk hunk --version

Windows 上需使用 mise 2026.8.6 或更新版本，更早版本会报unsupported env: windows/amd64。另外，Hunk 也作为 Omarchy 的默认工具随其发行，由 Omarchy 通过 mise 完成安装。

通过 Nix 安装

仓库从flake.nix导出default包。在 Hunk 的克隆目录中：

nix build ./result/bin/hunk --version

Nix 安装属于源码构建，其升级由 Nix 自身工具链管理（详见下文更新章节）。关于 Home Manager 模块与开发 shell 的细节，可参考仓库的 nix/README.md——该文档提供了 flake input 引入、environment.systemPackages/home.packages用法、programs.hunk模块配置（含enableGitIntegration将 Hunk 设为默认 Git pager）以及nix run github:modem-dev/hunk -- --help直跑方式。

验证安装

安装完成后，通过帮助命令验证：

hunk --help

预期输出以Usage: hunk <command> [options]开头。如果 shell 无法找到 Hunk，请确认全局 npm、Homebrew、mise 或~/.hunk/bin目录已在PATH中，然后打开一个新 shell 重试。

更新 Hunk：hunk update 的完整语义

自 Hunk 0.20 起，hunk update是让 npm、Homebrew 与默认 install-script 安装升级到最新版的规范方式，它会调用当初安装 Hunk 的包管理器：

hunk update # 安装最新 release hunk update --check # 仅检查，不安装 hunk update 0.20.0 # 安装指定的 npm 或默认 install-script release

若 Hunk 误判了安装方式，可用--method显式指定：--method npm、--method brew或--method curl。

各安装方式的更新归属

• npm（含 bun/pnpm 全局安装）：原地更新，实际执行的命令取决于检测到的客户端（npm install --global、bun add --global或pnpm add --global，见 selfUpdate.ts）。
• Homebrew：原地执行brew upgrade hunk；Homebrew 安装无法指定精确版本（见 selfUpdate.ts 的报错逻辑）。
• 默认 install-script 安装：重新运行安装器并带上目标版本（通过子进程环境变量HUNK_VERSION传递，见 selfUpdate.ts），并沿用与前述一致的条件性校验和验证。
• mise、Nix 与本地源码构建：不属于 Hunk 自己管理的范围，分别改用mise up hunk、Nix 配置或bun run install:bin；hunk update会打印对应指引并退出（非--check时返回非零码）。
• 自定义HUNK_INSTALL_DIR：同样需要带着相同目录重新运行安装器。

安装来源的自动识别原理

hunk update与启动时的更新提示共用同一套来源判定逻辑（见 installSource.ts）：先读取显式声明的HUNK_INSTALL_SOURCE环境变量；再按最强信号依次匹配/nix/store/路径前缀、mise 的mise/installs目录结构、Homebrew 的Cellar/homebrew/linuxbrew路径段（并排除node_modules以避免把 Homebrew 前缀下由 npm 拥有的全局包误判）、install script 的.hunk/bin相邻路径段；本地源码构建则通过~/.local/bin（或 Windows 的 Programs 目录）及未打标签的版本号识别，最终兜底判定为 npm。

更新检查的节流与静默来源

启动时的自动更新检查对每个用户配置文件每 4 小时最多执行一次（STARTUP_RELEASE_CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000，见 updateNotice.ts），检查结果会持久化到应用状态文件以避免重复请求。同时，mise、pacman 与本地源码构建（SILENT_INSTALL_SOURCES）不会弹出更新提示——mise 安装由 omarchy 在启动前已通过mise use -g aqua:modem-dev/hunk完成升级，源码构建则由开发者自己的重建流程管理（见 updateNotice.ts）。若需在 CI 等确定性场景中彻底关闭启动提示，可设置HUNK_DISABLE_UPDATE_NOTICE=1（updateNotice.ts）。

版本渠道查询：各渠道各查各的源

版本查询严格遵循"哪个渠道安装、就查哪个渠道的源"（见 latestRelease.ts）：npm 安装读取hunkdiff包的 dist-tags（latest与beta），Homebrew 安装读取 Homebrew formula API，curl 安装读取 Hunk release 端点（默认）或 GitHub releases API（直连回退）。Nix、mise 与源码构建则不会借用其他渠道的版本号，因此 Homebrew 用户不会再看到brew尚无法安装的 release。

各安装方式的更新速查表

小结

Hunk 的安装体系围绕"平台适配"与"安装归属清晰"两个原则设计：macOS/Linux 默认走自包含二进制的 install script，Windows 走 npm 或 mise；安装脚本内置 SHA256SUMS 校验、冲突安装检测与匿名 release 发现机制；hunk update则严格按安装来源委派给对应的包管理器，确保无论哪种方式安装都能找到正确的升级路径。完成安装后，可继续阅读官方快速上手文档，开始你的首次工作树 review：review your first working tree。

• 开发工具
• 代码评审
• CLI
• AI 应用