mise cache 缓存管理命令详解：清理、定位、修剪与任务缓存检查

mise cache 缓存管理命令详解：清理、定位、修剪与任务缓存检查

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise

mise cache是 mise 中用于统一管理各类缓存（工具元数据缓存、环境计算缓存、任务输出缓存）的命令组。本文将基于 cache.md 及配套子命令文档，结合仓库源码与 cache-behavior.md，完整讲解mise cache的四个子命令（clear、path、prune、task）、相关设置项、环境变量及底层实现原理，让读者掌握如何按症状精准清理缓存、预览与执行修剪、以及检查任务缓存命中情况。

mise cache命令总览

mise cache是 mise CLI 中管理缓存的一级命令。根据 cache.md：

• 用法：mise cache [SUBCOMMAND]
• 效果：read-only（不带子命令时只读）
• 源码入口：src/cli/cache/mod.rs

直接运行mise cache（不带任何参数）会输出当前缓存目录路径。从 mod.rs 的run实现可以看到，当没有子命令时，它直接打印MISE_CACHE_DIR指向的目录：

None => { // just show the cache dir miseprintln!("{}", env::MISE_CACHE_DIR.display()); Ok(()) }

支持以下四个子命令：

mise cache path：查看缓存目录

mise cache path用于显示当前缓存目录的绝对路径：

• 用法：mise cache path
• 别名：dir
• 效果：read-only
• 源码：src/cli/cache/path.rs

源码实现非常简洁，直接打印环境变量MISE_CACHE_DIR对应的路径（path.rs）：

pub(super) fn run(self) -> Result<()> { miseprintln!("{}", env::MISE_CACHE_DIR.display()); Ok(()) }

MISE_CACHE_DIR的默认位置遵循 mise 的 directories 规范（~/.cache/mise，具体随平台不同）。你可以通过设置该环境变量将缓存重定向到自定义目录（例如在 CI 中指向可持久化的工作区缓存目录）。

mise cache clear：清理缓存

mise cache clear用于删除缓存文件：

• 用法：mise cache clear [--task <TASK>] [TOOL]…
• 别名：c、clean
• 效果：modifies state
• 源码：src/cli/cache/clear.rs

参数与选项

清理指定工具的元数据缓存

工具缓存位于MISE_CACHE_DIR下按工具名（kebab-case 形式）组织的子目录中。例如清理 Node.js 的版本元数据：

mise cache clear node mise ls-remote node # 强制重新拉取远程版本列表

从 clear.rs 可以看到，指定的工具名会先被转换为 kebab-case（p.to_kebab_case()），然后拼接出CACHE/<tool>路径；非法（转换后为空）的工具名会打印警告并跳过。未指定TOOL时，则通过cache::cache_dirs()枚举所有缓存子目录。

清除所有缓存

不带参数运行mise cache clear会清空全部缓存，同时还会连带清除环境缓存与任务产物缓存（clear.rs）：

if self.tool.is_none() { CachedEnv::clear()?; let task_cache_state = crate::dirs::STATE.join("task-artifacts"); handle_remove_result(&task_cache_state, remove_all_with_retry(&task_cache_state))?; }

即：无参数执行时，除了工具元数据缓存，还会清空env-cache/（环境缓存）与state/task-artifacts（任务产物缓存）。这一点在 cache-behavior.md 中也有说明：完整mise cache clear会移除缓存根目录下的所有条目，包括其他项目的条目、无法验证归属的遗留条目以及环境缓存。

值得注意的细节：删除目录时若遇到DirectoryNotEmpty错误（例如清理过程中缓存被并发重建），源码会将其视为可容忍情况并继续（clear.rs），而PermissionDenied等其他错误则会正常向上传播——这由 clear.rs 中的单元测试验证。

使用--task清除任务输出缓存

mise cache clear --task <TASK>只清除指定任务（或匹配模式）的输出缓存条目，例如：

mise cache clear --task build

根据 clear.rs，该模式会先在当前配置中解析任务名/模式，逐个任务调用clear_task_cache，最后汇总输出清除的条目数与释放的空间大小。--task仅删除能够验证任务归属的条目，会跳过无法验证归属的遗留条目（详见 cache-behavior.md 的 Task caches 一节）。

mise cache prune：修剪过期缓存

mise cache prune用于移除过期的缓存文件：

• 用法：mise cache prune [-v --verbose] [--dry-run] [TOOL]…
• 别名：p
• 效果：modifies state
• 源码：src/cli/cache/prune.rs

默认行为与可配置阈值

默认情况下，该命令删除30 天内未被访问过的文件。该阈值由MISE_CACHE_PRUNE_AGE环境变量控制，对应配置项cache_prune_age（默认值为30d）：

[cache_prune_age] default = "30d" description = "Delete files in cache that have not been accessed in this duration"

从 prune.rs 可以看到实现细节：cache_prune_age解析为Duration，解析失败时回退到 30 天默认值（Duration::from_secs(30 * 24 * 60 * 60)）。

age: settings .cache_prune_age_duration() .unwrap_or(Duration::from_secs(30 * 24 * 60 * 60)),

需要区分两个概念（cache-behavior.md 的 Cache auto-pruning 一节）：

• 缓存新鲜度（freshness）：如远程版本列表默认 1 小时刷新一次，到期会重新拉取；
• 修剪年龄（prune age）：文件未被访问超过该时长才被删除。

因此一个过期（fresh 已失效）的版本列表可能在文件被修剪之前很久就被重新拉取覆盖了，二者互不冲突。如果你希望禁用基于访问年龄的自动修剪，可设置cache_prune_age = "0s"。

参数与选项

实战用法

mise cache prune --dry-run # 预览：列出会被删除的过期文件 mise cache prune # 实际执行修剪 mise cache prune -v # 修剪并显示具体删除了哪些文件 mise cache prune node python # 只修剪 node 与 python 的缓存

修剪完成后，命令会输出汇总信息（cache pruned N files, SIZE）。与clear类似，未指定工具时也会用cache_prune_age修剪环境缓存目录，但环境缓存使用自身的 TTL（env_cache_ttl）作为修剪年龄（prune.rs）。

在 CI 场景下，cache-behavior.md 建议优先缓存已安装的工具（这通常节省最多时间）；元数据缓存对重复 job 也有帮助，但缓存键应包含运行平台与项目配置信息，并确保管线在无缓存恢复时也能正常工作。

mise cache task：检查任务输出缓存

mise cache task用于检查某个任务的输出缓存条目：

• 用法：mise cache task [-J --json] <TASK>
• 效果：read-only
• 源码：src/cli/cache/task.rs

参数与选项

表格输出

默认情况下，mise cache task build会以表格形式展示每个缓存条目（task.rs）：

当匹配到多个任务时会额外增加Task列；如果没有匹配条目，则输出No output cache entries for <task>。任务名解析由resolve_tasks完成（task.rs）：支持expand_colon_task_syntax的:语法、//前缀的模式匹配、workspace 项目任务（is_workspace_project_task），以及任务别名（build_task_ref_map）；任务不存在时会报错并提示可用mise tasks ls --all --hidden列出所有任务。

JSON 输出

配合-J可得到结构化结果，便于脚本解析：

mise cache task build -J

输出为 JSON 数组，每个元素包含task（任务显示名）、root（任务工作目录）、entries（缓存条目数组），由 task.rs 中的serde_json::to_string_pretty生成。

任务缓存的配置、缓存键与重跑行为详见 tasks/caching.md。任务输出缓存还受MISE_TASK_CACHE_MAX_AGE环境变量（task_cache_max_age设置）约束：超过该时长的输出缓存条目会在存入新条目后被移除，该限制独立于cache_prune_age，设为0s或不设置即禁用年龄限制（见 settings.toml）。

三类缓存的行为总览

理解mise cache各类子命令，关键在于 mise 将三类缓存分开管理（cache-behavior.md）：

1. 工具元数据缓存（Tool Cache）：后端（backend）在MISE_CACHE_DIR下存储的元数据，包括远程版本列表，以及适用的别名、可执行文件目录、插件exec-env结果等。远程版本列表默认1 小时新鲜，由fetch_remote_versions_cache（默认1h）控制。可通过mise cache clear node强制刷新后执行mise ls-remote node重新拉取。

2. 环境缓存（Environment Caching）：实验性设置env_cache（默认false）启用后，将计算出的环境缓存在磁盘上的state/env-cache/目录（不在工具元数据缓存内），适用于环境提供器昂贵或存在嵌套 mise 调用的场景：

   # ~/.config/mise/config.toml [settings] env_cache = true env_cache_ttl = "1h" # 可选；默认 1 小时

   缓存键包含配置路径与修改时间、解析后的工具版本、相关设置、基础PATH与 mise 版本；条目在env_cache_ttl后过期，插件声明的监听文件（watched files）也可使其失效。mise activate与mise exec会建立会话加密密钥并由嵌套命令继承——缓存复用要求密钥一致，因此非相关会话不保证命中；缓存虽在磁盘上加密，但继承会话密钥的进程可以读取。若改动 dotenv 文件或_.source脚本后嵌套命令仍在使用旧环境，应清空或禁用该缓存；外部服务变更（如轮换的密钥）不属于文件变更，需选择合适的 TTL 或关闭环境缓存。需要强制重算环境时可在启动前设置：

   MISE_ENV_CACHE=0 mise exec -- npm test

   对所有命令禁用则设置env_cache = false。注意：当前普通环境指令不支持按值设置cacheable = false，因此时间戳模板在环境缓存有效期内可能被复用。环境插件在MiseEnv返回值中声明可缓存性与监听文件，详见 env-plugin-development.md。

3. 任务缓存（Task Caches）：任务可基于源文件/输出新鲜度跳过工作或恢复历史输出。使用mise cache task build检查、mise cache clear --task build清除；配置、缓存键与重跑行为见 tasks/caching.md。

按症状选择缓存操作

mise 的官方建议是"从与症状相关的缓存入手"（cache-behavior.md）：清空版本列表不会重装工具，清除环境缓存不会改变配置。常见操作组合：

mise cache path # 查看实际缓存目录 mise cache clear node # 清除 Node 的工具元数据 mise cache prune --dry-run # 预览过期缓存文件 mise cache clear --task build # 仅清除 build 任务输出缓存 mise cache task build # 检查 build 任务输出缓存条目

相关文档

• Cache behavior：三类缓存的完整行为说明。
• All commands：全部 CLI 命令参考。
• Task output caching：任务输出缓存的配置、缓存键与重跑行为。
• Global flags and argument syntax：全局参数与参数语法。

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise