Exodrive

文档

Exodrive 把开发缓存搬到外接磁盘。副本通过校验后，才释放本机空间。 本页讲窗口、命令行和账本。

安装

一条命令安装最新版本：

curl -fsSL https://jungley8.github.io/exodrive/install.sh | sh

Windows 上在 PowerShell 里运行：

irm https://jungley8.github.io/exodrive/install.ps1 | iex

脚本下载对应本机的包，并用 SHA256SUMS 校验。校验不通过就停止，不写入任何文件。 macOS 上把 Exodrive.app 装到 ~/Applications，命令行工具装到 ~/.local/bin；Linux 上只装命令行工具；Windows 上把两个程序装到 %LOCALAPPDATA%\Programs\Exodrive。

运行前可以先读脚本：install.sh 或 install.ps1

只装其中一项，或装指定版本：

curl -fsSL https://jungley8.github.io/exodrive/install.sh | sh -s -- --cli
curl -fsSL https://jungley8.github.io/exodrive/install.sh | sh -s -- --app
curl -fsSL https://jungley8.github.io/exodrive/install.sh | sh -s -- --version v0.8.0

install.ps1 接受 -Version 和 -Dir。

从浏览器下载的文件带隔离标记，macOS 首次打开时会要求确认：右键点按应用，选择打开。 脚本用 curl，不会加这个标记。

也可以从发布页下载，再校验：

shasum -a 256 -c SHA256SUMS

从源码构建

git clone https://github.com/Jungley8/exodrive
cd exodrive
make build        # 生成 bin/exodrive 与 bin/exodrive-gui
make app          # 生成 bin/Exodrive.app，ad-hoc 签名

需要 Go 1.27 或更高版本。

使用窗口

窗口启动时检查这台电脑，列出所有可迁移的缓存。

  1. 选择目录。点选择打开 macOS 的目录面板。 面板列出所有已连接的磁盘。也可以直接输入路径。
  2. 勾选缓存。点全选，或点卡片上的勾选框。
  3. 迁移。点迁移。看清弹窗里的清单，再点一次迁移。

窗口有两条容量条。左边是本机可用空间和缓存占用，右边是所选磁盘的可用空间和已迁入的大小。

每个缓存是一张卡片：大小、状态、目录、副本，以及 Exodrive 所做的改动。 卡片上还有唯一适合该状态的操作。

左侧栏按工具链分组：Node、Python、Rust、Go、Apple、JVM、Mobile、Homebrew、Docker。列表上方的筛选器 保留一个位置。切换筛选会清空勾选，所以迁移永远只作用于屏幕上能看到的缓存。

首次启动显示三步引导。点跳过关闭它，之后不再出现。

使用命令行

扫描全部工具链：

exodrive check

针对某个目录检查一个缓存，不动数据：

exodrive preflight npm.cache --target=/Volumes/External/exodrive

把缓存搬到目录：

exodrive migrate --target=/Volumes/External/exodrive --all
exodrive migrate --target=/Volumes/External/exodrive --tools=npm,pnpm

只看计划，不动数据：

exodrive migrate --target=/Volumes/External/exodrive --all --dry-run

找出早先改动遗留的缓存：

exodrive orphans
exodrive orphans --clean

命令行返回脚本可读的退出码。被拒绝的迁移是失败，不是警告。

账本

Exodrive 写 ~/.exodrive/manifest.json。每次迁移加一条记录： 条目、原路径、新目录、让工具指向副本的改动、大小、时间和副本摘要。

写文件时加锁，两个进程不会互相覆盖。同一条目只出现一次。

设置 EXODRIVE_MANIFEST_PATH 可以把文件放到别处。

账本要和外接磁盘一起保留。搬回需要两者都在。

检查已迁移的副本

迁移时会记录副本摘要。点卡片上的检查副本，或者运行：

exodrive verify npm.cache
exodrive verify --all
exodrive verify --all --json

检查会重新读取副本，与记录的摘要比对。它不向磁盘写入任何内容。命令行每个副本输出一行；只要有一项不通过，退出码就是 1。

  • ok：副本与迁移时写入的字节一致。
  • changed：副本里有文件与迁移时不同。请搬回后重新迁移。
  • missing：副本不在记录的路径上。请连接外接磁盘。
  • unverified：记录里没有摘要。旧版 Exodrive 写下的记录没有摘要。

无法证明的副本，检查不会报告 ok。

把缓存搬回来

点卡片上的搬回，然后确认。

也可以用命令行，配合条目 ID：

exodrive check                     # 列出条目 ID
exodrive rollback npm.cache

Exodrive 把缓存复制回原目录并校验副本。校验通过后删除磁盘上的副本， 最后删除账本记录。

两份副本内容不同时，Exodrive 停止。它保留两份数据和记录，因为无法替你选择。

要保留本机目录，执行 exodrive rollback --keep-local <item>。 该命令删除磁盘上的副本，并移除记录。窗口在失败卡片上提供同样的操作： 保留本机目录。

停止窗口

macOS 关闭窗口时不询问。Exodrive 无法在迁移过程中挂住窗口。

迁移开始前写一条记录，结束时删除。下次启动读到这条记录，会指出当时正在变更的缓存。

长迁移可以点本个完成后停止。正在迁移的这一项会先做完。

拷贝中途关闭窗口，磁盘上会留下不完整的副本，本机的缓存完好。 重新检查：卡片仍显示在本机，就再迁移一次。

故障处理

窗口显示怎么做
无法迁移 原因写在卡片上。处理完点重新检查。
有程序仍在使用这个缓存 退出该程序，点重新检查。
副本与原文件不一致 点重试。再次失败说明问题在磁盘。
这块磁盘不能存放缓存 改选 APFS、HFS+、ext4、btrfs、zfs、xfs、f2fs、bcachefs 或 NTFS 上的目录。
你的 shell 设置了缓存路径 从 shell 移除窗口指出的变量，然后重试。
磁盘空间不足 先释放磁盘空间，或少选几个缓存。
不能迁移，卡片指出这是模拟器目录 该目录保留在本机。在 Xcode 里删除不再使用的模拟器。
Xcode 在原位置重建了真实目录 回滚会先比对两个目录。不一致时两个目录都保留。点保留本机目录删除副本。
没有这次迁移的记录 重新检查。记录文件可能在别的位置。

找不到的工具链不会出现在列表里。窗口读取登录 shell 的 PATH。 把工具加进这个 PATH，再点重新检查。

报告问题

每次失败，Exodrive 向 ~/.exodrive/failures.jsonl 写入一行。 这一行包含时间、版本、平台、步骤、类型、缓存和消息。用户主目录显示为 ~。

失败卡片上的复制详情复制这一条失败。窗口底部的报告问题 显示报告将携带的完整文字。对话框可以复制文字，或打开预填好的 GitHub issue。 提交前可以修改。Exodrive 自身不发送任何内容。

在终端运行 exodrive doctor，输出同样的信息。

设置 EXODRIVE_NO_FAILURE_LOG=1 可关闭日志。删除该文件即清除全部记录。

平台

  • macOS 13 或更高版本：窗口在这里发布，所有测试都在这里运行。
  • Linux：命令行工具可构建可运行，CI 在 Ubuntu 上测试。
  • Windows：窗口与命令行工具都发布。Windows 上没有测试。

没有承诺的系统上出的问题仍然是问题。报告后按同样的检查修复。

安全

Exodrive 以你的身份运行。它读取本机的工具设置，写入工具使用的文件。 它不开放任何网络服务。

更新检查只读取 GitHub 的公开发布列表。设置 EXODRIVE_NO_UPDATE_CHECK=1 可关闭检查。

安全问题请按仓库里的安全策略报告。