mise 目录结构完全指南配置、缓存、状态与工具安装目录的职责划分与迁移【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/misemisedev tools、env vars、task runner将全局配置、可丢弃的缓存元数据、机器本地状态与已安装的工具与插件分别存放在四个相互隔离的目录中。本文基于 docs/directories.md 并结合仓库源码完整讲解每个目录的默认位置、环境变量覆盖方式、可安全共享/删除的内容以及 system 级安装与 shims 的特殊行为。读完你就能独立规划 mise 在单机、CI 与 dotfiles 仓库中的目录布局并避开MISE_INSTALLS_DIR设置错位、缓存目录混用等典型陷阱。目录总览四类数据、四处存放mise 把「配置」「缓存」「状态」「数据」严格分离其目录解析逻辑集中在 src/env.rs用途LinuxmacOSWindows覆盖方式全局配置~/.config/mise~/.config/mise%USERPROFILE%\.config\miseMISE_CONFIG_DIR否则XDG_CONFIG_HOME/mise缓存~/.cache/mise~/Library/Caches/mise%TEMP%\miseMISE_CACHE_DIR否则XDG_CACHE_HOME/mise本地状态~/.local/state/mise~/.local/state/mise%USERPROFILE%\.local\state\miseMISE_STATE_DIR否则XDG_STATE_HOME/mise工具与插件安装~/.local/share/mise~/.local/share/mise%LOCALAPPDATA%\miseMISE_DATA_DIR否则XDG_DATA_HOME/mise几点全局原则表中均为未设置任何MISE_*或XDG_*覆盖时的默认值。mise cache path直接打印当前生效的缓存路径实现见 src/cli/cache/path.rsmise doctor会报告解析后的全部 mise 目录见 src/cli/doctor/mod.rs 中的 state/data/cache 目录输出。目录覆盖变量必须在启动 mise 的进程中预先设置并且要在 shell、编辑器、CI 任务之间保持一致否则同一台机器上不同入口解析出的路径会不同。四个目录必须保持分离尤其不要把MISE_CACHE_DIR指向包含配置或已安装工具的目录——缓存清理会直接删除其中内容。~/.config/mise全局配置覆盖变量$MISE_CONFIG_DIR默认值${XDG_CONFIG_HOME:-$HOME/.config}/mise存放全局配置通常是config.toml。可移植的配置可以放进 dotfiles 仓库做版本管理但凭据与机器相关取值绝不能放进共享文件。项目级配置位于项目目录内详见 configuration 文档。从源码看当MISE_CONFIG_DIR被显式设置到非默认位置时mise 会据此过滤掉默认目录下的配置避免两处配置同时生效src/config/mod.rs 与 src/env.rs 中的MISE_CONFIG_DIR_OVERRIDDEN标记。~/.cache/mise可丢弃的元数据缓存覆盖变量$MISE_CACHE_DIR默认值${XDG_CACHE_HOME:-$HOME/.cache}/misemacOS 为~/Library/Caches/mise这里存放 mise 的内部缓存例如某个工具的全部可用版本列表等元数据是完全可再生的。清理方式mise cache clear # 清空全部缓存 mise cache clear node # 仅清理指定工具的缓存参数如 node、python mise cache clear --task some-task # 清理指定任务的输出缓存从 src/cli/cache/clear.rs 的实现可以看到不带参数时除删除各缓存目录外还会同时清除STATE下的env-cache与task-artifacts支持--outdate模式不删除文件而是把所有缓存文件时间戳置零使其按过期策略失效清理过程容忍「目录被并发重建」的情况DirectoryNotEmpty错误会被放行适合在安装进行中调用。只要缓存与安装目录相互独立mise cache clear不会卸载任何已安装的工具。缓存机制的完整说明见 cache-behavior 文档。~/.local/state/mise机器本地状态覆盖变量$MISE_STATE_DIR默认值${XDG_STATE_HOME:-$HOME/.local/state}/mise存放三类关键状态信任记录mise trust对配置文件做出的信任/忽略决策src/cli/trust.rs 中的trust、untrust、ignore命令被跟踪的配置路径供mise config ls --tracked-configs展示、mise prune计算哪些版本仍被需要的跟踪列表src/cli/config/ls.rs加密的环境缓存env-cache文件保存计算好的工具环境变量结果且默认使用加密密钥加密存储见 src/toolset/env_cache.rs 的encrypt_data与 第 148 行 的dirs::STATE.join(env-cache)。该目录必须留在本机。删除它会丢失信任决策与其他状态只想刷新缓存值时应使用mise cache clear而不是手动删除 state 目录。~/.local/share/mise工具与插件安装根目录覆盖变量$MISE_DATA_DIR默认值${XDG_DATA_HOME:-$HOME/.local/share}/mise包含工具安装、插件、shims 与命令包装器。核心约束不要同时让 asdf 与 mise 管理同一个安装目录——两者的文件系统布局虽相似但互不协调对共享状态的改动。CI 场景提示安装工具缓存的迁移必须匹配操作系统、架构、编译配置及原生库依赖把该目录在任意机器之间复制不是可移植的安装方式CI 中复用安装应缓存下面的installs目录。downloads临时下载物插件在安装过程中可能把下载的 tarball 等资源写到这里。mise 默认在安装/卸载后自动删除这些文件需要调试 backend/插件安装行为时可设置always_keep_download保留它们。该目录不是受支持的下载缓存某些 backend 在目标文件已存在时可能跳过下载但这是 backend 特定行为、不保证。CI 或离线工作流中要避免重复安装工具应缓存~/.local/share/mise/installs。plugins插件安装位置mise plugins install会把插件安装到此目录。开发插件时若该路径下尚无已安装的插件可以用符号链接指向你的开发副本mkdir -p ~/.local/share/mise/plugins ln -s ~/src/mise-my-tool ~/.local/share/mise/plugins/my-toolinstalls已安装的工具版本存放安装好的工具版本。例如mise install node24.0.0会安装到数据目录下的installs/node/24.0.0。mise 还会创建版本前缀与别名符号链接指向具体安装从 src/runtime_symlinks.rs 的实现看24会链接到24.0.0、latest会链接到当前最新版本插件声明的别名如lts也会被生成对应链接。因此查找时应使用命令而不是自行拼接路径mise where node # 打印当前选中的安装目录 mise which node # 打印当前选中的可执行文件路径MISE_INSTALLS_DIR的使用与陷阱MISE_INSTALLS_DIR环境变量可单独覆盖安装目录位置它在mise 启动时被读取src/env.rs 中MISE_INSTALLS_DIR优先于MISE_DATA_DIR/installs。两个硬性要求必须在调用 mise 之前设置并在之后的所有 mise 与 shim 调用中保持设置绝不能写在mise.toml的[env]段里——[env]描述的是 mise 导出给子进程的环境此时 mise 早已完成安装目录的选择。在[env]中设置它会造成「安装时用一个目录、后续命令和 shim 又去找另一个目录」的错位。shimsIDE 集成与兜底方案mise 生成的 shims 存放于此一般用于 IDE 集成或mise activate无法生效的场景。设置项shims_dir仅全局设置会展开~且必须解析为绝对路径环境变量覆盖MISE_SHIMS_DIR配置解析层对shims_dir的校验可在 src/config/settings.rs 的normalize_storage_dirs中看到所有存储目录设置都会展开~非绝对路径会直接报错must resolve to an absolute path。mise reshim可以发布到共享可执行目录如~/.local/bin或/usr/local/bin并且只会替换或删除它自己识别为 mise shim 的条目。但要注意mise 的其他功能mise activate、hook-env、内部依赖查找仍会把整个 shim 目录当作完整PATH条目来过滤因此使用这些功能时请使用专用目录存放 shims。command-wrappers/bin[wrappers]分发由[wrappers]配置的分发 shims 放在这里。该目录由 mise 托管增删命令包装器后需要执行mise reshim使其生效。系统级安装与系统 shims系统级system安装与 shims 针对需要全机器可见的场景默认系统安装目录/usr/local/share/mise/installs默认系统 shims 目录/usr/local/share/mise/shims可通过仅全局生效的设置system_installs_dir、system_shims_dir或环境变量MISE_SYSTEM_INSTALLS_DIR、MISE_SYSTEM_SHIMS_DIR修改两个路径同样会展开~且必须是绝对路径校验同样在 src/config/settings.rs。对应命令mise install --system # 写入系统安装根目录 mise reshim --system # 重建系统 shimsmise永远不会自动提权。默认目录不可写时需要预先以必要权限执行安装或用设置把路径重定向到可写位置。发行版共存user 与 system 存储合并示例某些发行版会把系统与用户存储放在一起同时保留系统配置。例如 Omarchy 可以把所有工具产物都放在用户主目录[settings] system_installs_dir ~/.local/share/mise/installs shims_dir ~/.local/share/mise/shims system_shims_dir ~/.local/share/mise/shims该配置下的行为保证依据 docs/directories.md 与源码中系统目录解析逻辑 src/env.rs当shims_dir与system_shims_dir相等时mise 用同一把锁管理一份合并的 shims 集合当系统安装根与用户安装根相等时该根目录被当作本地存储处理不会重复扫描与分类。目录规划速查可进 dotfiles 仓库~/.config/mise中的纯配置不含凭据可随时删除重建~/.cache/mise用mise cache clear必须留在本机~/.local/state/mise信任记录、跟踪配置、加密环境缓存可整体备份/迁移需谨慎~/.local/share/mise注意 OS/架构/原生库匹配CI 复用请缓存installs排查目录问题先mise doctor查看解析结果再用mise cache path确认缓存路径最后核对启动环境中的MISE_*/XDG_*变量是否在 shell、编辑器、CI 三处一致。【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mise 目录结构完全指南：配置、缓存、状态与工具安装目录的职责划分与迁移
mise 目录结构完全指南配置、缓存、状态与工具安装目录的职责划分与迁移【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/misemisedev tools、env vars、task runner将全局配置、可丢弃的缓存元数据、机器本地状态与已安装的工具与插件分别存放在四个相互隔离的目录中。本文基于 docs/directories.md 并结合仓库源码完整讲解每个目录的默认位置、环境变量覆盖方式、可安全共享/删除的内容以及 system 级安装与 shims 的特殊行为。读完你就能独立规划 mise 在单机、CI 与 dotfiles 仓库中的目录布局并避开MISE_INSTALLS_DIR设置错位、缓存目录混用等典型陷阱。目录总览四类数据、四处存放mise 把「配置」「缓存」「状态」「数据」严格分离其目录解析逻辑集中在 src/env.rs用途LinuxmacOSWindows覆盖方式全局配置~/.config/mise~/.config/mise%USERPROFILE%\.config\miseMISE_CONFIG_DIR否则XDG_CONFIG_HOME/mise缓存~/.cache/mise~/Library/Caches/mise%TEMP%\miseMISE_CACHE_DIR否则XDG_CACHE_HOME/mise本地状态~/.local/state/mise~/.local/state/mise%USERPROFILE%\.local\state\miseMISE_STATE_DIR否则XDG_STATE_HOME/mise工具与插件安装~/.local/share/mise~/.local/share/mise%LOCALAPPDATA%\miseMISE_DATA_DIR否则XDG_DATA_HOME/mise几点全局原则表中均为未设置任何MISE_*或XDG_*覆盖时的默认值。mise cache path直接打印当前生效的缓存路径实现见 src/cli/cache/path.rsmise doctor会报告解析后的全部 mise 目录见 src/cli/doctor/mod.rs 中的 state/data/cache 目录输出。目录覆盖变量必须在启动 mise 的进程中预先设置并且要在 shell、编辑器、CI 任务之间保持一致否则同一台机器上不同入口解析出的路径会不同。四个目录必须保持分离尤其不要把MISE_CACHE_DIR指向包含配置或已安装工具的目录——缓存清理会直接删除其中内容。~/.config/mise全局配置覆盖变量$MISE_CONFIG_DIR默认值${XDG_CONFIG_HOME:-$HOME/.config}/mise存放全局配置通常是config.toml。可移植的配置可以放进 dotfiles 仓库做版本管理但凭据与机器相关取值绝不能放进共享文件。项目级配置位于项目目录内详见 configuration 文档。从源码看当MISE_CONFIG_DIR被显式设置到非默认位置时mise 会据此过滤掉默认目录下的配置避免两处配置同时生效src/config/mod.rs 与 src/env.rs 中的MISE_CONFIG_DIR_OVERRIDDEN标记。~/.cache/mise可丢弃的元数据缓存覆盖变量$MISE_CACHE_DIR默认值${XDG_CACHE_HOME:-$HOME/.cache}/misemacOS 为~/Library/Caches/mise这里存放 mise 的内部缓存例如某个工具的全部可用版本列表等元数据是完全可再生的。清理方式mise cache clear # 清空全部缓存 mise cache clear node # 仅清理指定工具的缓存参数如 node、python mise cache clear --task some-task # 清理指定任务的输出缓存从 src/cli/cache/clear.rs 的实现可以看到不带参数时除删除各缓存目录外还会同时清除STATE下的env-cache与task-artifacts支持--outdate模式不删除文件而是把所有缓存文件时间戳置零使其按过期策略失效清理过程容忍「目录被并发重建」的情况DirectoryNotEmpty错误会被放行适合在安装进行中调用。只要缓存与安装目录相互独立mise cache clear不会卸载任何已安装的工具。缓存机制的完整说明见 cache-behavior 文档。~/.local/state/mise机器本地状态覆盖变量$MISE_STATE_DIR默认值${XDG_STATE_HOME:-$HOME/.local/state}/mise存放三类关键状态信任记录mise trust对配置文件做出的信任/忽略决策src/cli/trust.rs 中的trust、untrust、ignore命令被跟踪的配置路径供mise config ls --tracked-configs展示、mise prune计算哪些版本仍被需要的跟踪列表src/cli/config/ls.rs加密的环境缓存env-cache文件保存计算好的工具环境变量结果且默认使用加密密钥加密存储见 src/toolset/env_cache.rs 的encrypt_data与 第 148 行 的dirs::STATE.join(env-cache)。该目录必须留在本机。删除它会丢失信任决策与其他状态只想刷新缓存值时应使用mise cache clear而不是手动删除 state 目录。~/.local/share/mise工具与插件安装根目录覆盖变量$MISE_DATA_DIR默认值${XDG_DATA_HOME:-$HOME/.local/share}/mise包含工具安装、插件、shims 与命令包装器。核心约束不要同时让 asdf 与 mise 管理同一个安装目录——两者的文件系统布局虽相似但互不协调对共享状态的改动。CI 场景提示安装工具缓存的迁移必须匹配操作系统、架构、编译配置及原生库依赖把该目录在任意机器之间复制不是可移植的安装方式CI 中复用安装应缓存下面的installs目录。downloads临时下载物插件在安装过程中可能把下载的 tarball 等资源写到这里。mise 默认在安装/卸载后自动删除这些文件需要调试 backend/插件安装行为时可设置always_keep_download保留它们。该目录不是受支持的下载缓存某些 backend 在目标文件已存在时可能跳过下载但这是 backend 特定行为、不保证。CI 或离线工作流中要避免重复安装工具应缓存~/.local/share/mise/installs。plugins插件安装位置mise plugins install会把插件安装到此目录。开发插件时若该路径下尚无已安装的插件可以用符号链接指向你的开发副本mkdir -p ~/.local/share/mise/plugins ln -s ~/src/mise-my-tool ~/.local/share/mise/plugins/my-toolinstalls已安装的工具版本存放安装好的工具版本。例如mise install node24.0.0会安装到数据目录下的installs/node/24.0.0。mise 还会创建版本前缀与别名符号链接指向具体安装从 src/runtime_symlinks.rs 的实现看24会链接到24.0.0、latest会链接到当前最新版本插件声明的别名如lts也会被生成对应链接。因此查找时应使用命令而不是自行拼接路径mise where node # 打印当前选中的安装目录 mise which node # 打印当前选中的可执行文件路径MISE_INSTALLS_DIR的使用与陷阱MISE_INSTALLS_DIR环境变量可单独覆盖安装目录位置它在mise 启动时被读取src/env.rs 中MISE_INSTALLS_DIR优先于MISE_DATA_DIR/installs。两个硬性要求必须在调用 mise 之前设置并在之后的所有 mise 与 shim 调用中保持设置绝不能写在mise.toml的[env]段里——[env]描述的是 mise 导出给子进程的环境此时 mise 早已完成安装目录的选择。在[env]中设置它会造成「安装时用一个目录、后续命令和 shim 又去找另一个目录」的错位。shimsIDE 集成与兜底方案mise 生成的 shims 存放于此一般用于 IDE 集成或mise activate无法生效的场景。设置项shims_dir仅全局设置会展开~且必须解析为绝对路径环境变量覆盖MISE_SHIMS_DIR配置解析层对shims_dir的校验可在 src/config/settings.rs 的normalize_storage_dirs中看到所有存储目录设置都会展开~非绝对路径会直接报错must resolve to an absolute path。mise reshim可以发布到共享可执行目录如~/.local/bin或/usr/local/bin并且只会替换或删除它自己识别为 mise shim 的条目。但要注意mise 的其他功能mise activate、hook-env、内部依赖查找仍会把整个 shim 目录当作完整PATH条目来过滤因此使用这些功能时请使用专用目录存放 shims。command-wrappers/bin[wrappers]分发由[wrappers]配置的分发 shims 放在这里。该目录由 mise 托管增删命令包装器后需要执行mise reshim使其生效。系统级安装与系统 shims系统级system安装与 shims 针对需要全机器可见的场景默认系统安装目录/usr/local/share/mise/installs默认系统 shims 目录/usr/local/share/mise/shims可通过仅全局生效的设置system_installs_dir、system_shims_dir或环境变量MISE_SYSTEM_INSTALLS_DIR、MISE_SYSTEM_SHIMS_DIR修改两个路径同样会展开~且必须是绝对路径校验同样在 src/config/settings.rs。对应命令mise install --system # 写入系统安装根目录 mise reshim --system # 重建系统 shimsmise永远不会自动提权。默认目录不可写时需要预先以必要权限执行安装或用设置把路径重定向到可写位置。发行版共存user 与 system 存储合并示例某些发行版会把系统与用户存储放在一起同时保留系统配置。例如 Omarchy 可以把所有工具产物都放在用户主目录[settings] system_installs_dir ~/.local/share/mise/installs shims_dir ~/.local/share/mise/shims system_shims_dir ~/.local/share/mise/shims该配置下的行为保证依据 docs/directories.md 与源码中系统目录解析逻辑 src/env.rs当shims_dir与system_shims_dir相等时mise 用同一把锁管理一份合并的 shims 集合当系统安装根与用户安装根相等时该根目录被当作本地存储处理不会重复扫描与分类。目录规划速查可进 dotfiles 仓库~/.config/mise中的纯配置不含凭据可随时删除重建~/.cache/mise用mise cache clear必须留在本机~/.local/state/mise信任记录、跟踪配置、加密环境缓存可整体备份/迁移需谨慎~/.local/share/mise注意 OS/架构/原生库匹配CI 复用请缓存installs排查目录问题先mise doctor查看解析结果再用mise cache path确认缓存路径最后核对启动环境中的MISE_*/XDG_*变量是否在 shell、编辑器、CI 三处一致。【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考