简体中文
macOS 客户端
一个原生的 SwiftUI 小工具,调用应用内附带的 YunBox 命令行,复用同一套 Git/LFS 检查。
安装
从官网下载最新的 YunBox-macOS.zip,解压后把 YunBox 拖进「应用程序」。本机需要 Node.js 22.18+。从 0.1.6 起客户端要求 macOS 26 或更新;0.1.5 及更早版本最低支持 macOS 14。
从 0.1.5 起,安装包经过 Apple 公证,双击就能打开,不会再提示无法验证开发者。
0.1.4 及更早的版本
这些版本没有经过公证。第一次打开如果提示无法验证开发者,到「系统设置 → 隐私与安全性」点「仍要打开」,或者在终端运行:
bash
xattr -dr com.apple.quarantine /Applications/YunBox.app0.1.4 及以前的客户端还没有自动更新,建议直接下载最新版本替换。
也可以从源码构建,需要 Xcode 27.1(包含 macOS 27.0 SDK),与发布版使用相同的工具链配置:
bash
pnpm install
./script/build_and_run.sh --install # 安装到 ~/Applications/YunBox.app 并打开新手引导
首次打开会依次检查 Node.js、Git 和 Git LFS,选择 Git 仓库,设置推送保护,再选择是否接入素材存储。可以稍后设置,也能从「帮助 → 新手引导…」或「设置 → 推送保护」重新打开。
推送保护默认只针对所选仓库,超限时询问是否继续;关闭 App 后检查和确认框仍然工作,无人确认时取消推送。禁推时段始终阻止推送。无需云存储也能单独使用推送保护。
「应用到本机所有仓库」是可选项:保留仓库原有钩子,检查通过后才上传。仓库自己配置的钩子目录会覆盖全局设置,向导会显示是否实际生效;已有其他全局钩子管理器时不会覆盖。可以在向导中移除全局保护。现有仓库包装层优先执行,避免重复检查。
存储初始化也会安装本仓库的推送保护;保留已经安装的钩子和确认方式。更多命令及限制见推送检查。
自动更新
客户端内置自动更新(Sparkle):每天在后台检查一次,有新版本时显示更新说明,点「安装更新」后自动下载、替换并重新打开。也可以从「云匣 YunBox → 检查更新…」随时检查,或在「设置 → 软件更新」里关闭自动检查、改为自动下载并安装。
更新包和更新说明都经过签名,客户端只安装签名与内置公钥一致的版本。0.1.4 及更早的版本还没有这个功能,需要手动下载一次。每个版本改了什么见更新日志,「帮助」菜单和「设置 → 软件更新」里也能打开。
界面语言
客户端有简体中文和英文界面,默认跟随系统。在「设置 → 语言」里可以单独选择,重新打开后生效;也可以在「系统设置 → 通用 → 语言与地区 → 应用程序」里设置,两处是同一个设置。更新提示里的说明也按界面语言显示。命令行输出的说明(例如 yunbox doctor 的检查项)目前只有中文;官网文档有简体中文和英文两种。
能做什么
- 推送体积:选择或拖入 Git 仓库,分别显示 Git pack 估算和 LFS 候选量、预算和超限状态;直连 COS 的仓库显示 LFS 实际需要上传的量,已在 COS 上的文件标为「已在 COS」。文件按大小降序,支持搜索、类型筛选、只看超限。
- 文件明细:选中文件查看推送前后的变化:图片可以并排、拖动分隔线或来回切换对比,文本显示差异,可以切换统一视图或左右分栏,其他文件可用「快速查看」打开前后两个版本。内容取自推送的提交,而不是工作区。也可以复制路径或在 Finder 中定位。
- 存储直连状态:仓库标题右侧显示仓库直连的存储和状态,例如「直连 COS · 正常」「直连 R2 · 需要处理」或「未接入存储」(腾讯云 COS 显示 COS;S3 兼容存储按 endpoint 显示 R2、AWS S3、MinIO,其他服务显示 S3)。点开「存储」面板逐项列出
yunbox doctor的结果和修复命令。 - 交给 AI 接入:存储面板里的「复制给 AI 的接入说明」生成一段提示词,按仓库用的存储(未接入时按面板里选的存储)写好步骤,粘贴给编程助手即可接入,见用 AI 编程助手接入。
- 一键接入:没接入的仓库先在面板里选择存储:
- 腾讯云 COS:选择已有 bucket 或新建私有 bucket、填写目录前缀,直接运行
git yunbox init。 - S3 兼容存储:选择 Cloudflare R2(填账户 ID)、AWS S3(填地域)、MinIO 或其他服务(填 endpoint),再填 bucket 和目录前缀,运行
git yunbox init --preset …。云匣不能列出或新建 S3 的 bucket,要先在服务自己的控制台建好私有 bucket。R2 的 token 只能限定到 bucket、不能限定到前缀,建议每个项目一个 bucket,见接入 R2 和 S3 兼容存储。可以顺带填写 Access Key ID 和 Secret Access Key,接入前先保存到本机。
- 腾讯云 COS:选择已有 bucket 或新建私有 bucket、填写目录前缀,直接运行
- 保存密钥:本机没有这个仓库所用存储的密钥时(检查项「COS 密钥」或「S3 密钥」失败),面板里出现保存表单:COS 填子账号的 SecretId / SecretKey,S3 填 Access Key ID / Secret Access Key。SecretKey 和 Secret Access Key 用安全输入框,只经标准输入交给
yunbox login(S3 为yunbox login --provider s3),不出现在命令行参数和日志里。 - 菜单栏的禁推状态:菜单栏显示云匣标志,当前仓库处在禁推时段时右上角多一个圆点。打开面板时图标的盖子掀开,关闭时合上,进入禁推时段时圆点会弹出;每次打开都会刷新项目状态,内容平滑过渡。开启系统「减弱动态效果」后,图标和面板直接切换,不播放动画。点开面板查看能否推送、今天的时间轴和未来 7 天的禁推分布;全局规则(本机所有仓库)和每个项目的规则分开列出,都可以勾选「工作时间」「周末」等预设(项目没装 pre-push 包装层时会顺带安装),项目可以「设为当前」,不在列表里的用「添加项目…」选择,或打开「编辑禁推时段…」自定义;没装 pre-push 包装层时可以直接安装。标题栏的开关可以一键关闭全部禁推时段(规则保留),也能定时关闭 30 分钟、1 小时或到今天结束,到点自动恢复。
- 素材类型:仓库标题右侧的「素材类型」按类型查看和调整 LFS 规则,见下面的素材类型。
- 最近的仓库:最多 12 个,切换时先显示上次的检查结果,后台重新检查完成后替换。除了在客户端里打开过的仓库,命令行在哪个仓库里运行过
init、hook、freeze、types、inspect、status或doctor(包括每次推送时的 pre-push 检查),这个仓库也会自动出现在列表里。记录只保存在本机的~/.config/yunbox/repositories.json,只包含仓库路径和时间;从列表移除的仓库,下次命令行再用到它时才重新出现。 - 已固定:右键仓库选「固定」,它会移到侧边栏顶部的「已固定」分组,不会被新仓库挤出列表,「清除最近列表」也不会清掉它;可以拖动调整顺序,右键「取消固定」放回最近列表。
⌘1–⌘9先分给已固定的仓库,再分给最近的仓库。 - 最近被拦截:侧边栏顶部显示最近 14 天内最多 5 个被拦截的仓库及最近一次原因和时间。鼠标悬停查看说明,点击打开检查;右键可隐藏快捷项,下次拦截时重新出现。
- 推送保护历史:点击工具栏的「推送保护历史」,或在「检查」菜单、仓库右键菜单打开。按项目查看多次记录的时间、禁推或超限原因、处理结果,以及用户填写的说明,包括「已阻止」「用户取消」「已确认继续」。「已确认继续」表示检查已放行,后续上传是否成功由 Git 返回。
- 本机存储与清理:历史仅保存在这台电脑的
~/.config/yunbox/push-history.json,不会上传或提交到仓库;默认保留最近 90 天,每项目最多 200 条,全部最多 5000 条。历史窗口的「清理历史」可清理当前项目或全部项目,清理前需要确认;不会改动推送保护、Git 配置、素材或密钥。旧版blocked-pushes.json中已有的最近一次记录会迁入;已被旧版覆盖的记录无法恢复。命令行设置了YUNBOX_CONFIG_DIR或XDG_CONFIG_HOME时,历史保存在指定目录;从程序坞或 Finder 打开的客户端需要使用同一目录才能看到。
素材类型
仓库标题右侧显示「素材类型 · 5/7 走 LFS」;有素材作为普通文件提交过时变成橙色的「素材类型 · N 个未走 LFS」。点开(或「检查 → 素材类型…」)就是图形界面版的 git yunbox types:
- 类型:贴图和图片、设计源文件、模型和动画、音频、视频、字体、压缩包,各自显示全部走 LFS、部分走 LFS 或未走 LFS,以及已加入 Git 的文件数和其中的 LFS 指针数。展开可以看到每个扩展名是否走 LFS。手写或
git lfs track加的规则标成「来自其他规则」,客户端不会删除它们。 - 添加和移除:「添加」追加这一类的规则(
git yunbox types add),「移除…」确认后删除 YunBox 生成的规则(git yunbox types remove);已经存为 LFS 指针的文件不会改动。上方的预置组合(游戏项目、设计稿、图片和音视频、全部类型)一键添加多个类型,已经全部走 LFS 的组合显示为勾选。 - 作为普通文件提交的素材:按原因分组列出:扩展名大小写不同(例如 Linux 上的
HERO.PNG)、已有规则但提交时还没有、没有规则。后两种可以点「从下一次提交起改用 LFS…」,确认后运行git yunbox types add <类型> --renormalize:加上规则,并把.gitattributes和这些文件当前的内容加入暂存区,下一次提交起存为 LFS 指针。已有的提交(历史)不变。大小写不同的扩展名需要单独加规则,面板里给出对应的命令。
所有改动只写入 .gitattributes 和暂存区,不会提交;命令的输出显示在面板底部,确认后自己提交。


左:面板顶部的预置组合和类型列表,音频的 *.wav 来自手写规则;右:滚动到下方的「作为普通文件提交的素材」。
文档入口
「帮助」菜单可以直接打开官网文档,按界面语言打开中文或英文页面。菜单栏面板的「使用说明」打开禁推时段,编辑窗口和存储面板里也有对应说明的链接。
快捷键
| 快捷键 | 作用 |
|---|---|
⌘O | 选择仓库 |
⌘1–⌘9 | 切换已固定和最近的仓库 |
⌘R | 重新检查 |
⌘. | 取消检查 |
⇧⌘C | 复制完整 JSON |
⌘, | 打开设置 |
窗口里的检查与实际 pre-push 收到的引用范围可能不同,最终推送仍由推送检查钩子按实际引用重新检查。更多细节见 客户端 README。