mise

Mise

概述

Mise 是一款多语言开发工具管理器，通过一个 CLI 管理工具版本、环境变量和任务运行。它用统一的项目级 mise.toml 配置取代 asdf、nvm、pyenv、direnv 和 Makefile。

适用场景： 管理项目中的多种语言运行时，定义可复现的开发环境，运行带依赖关系的项目任务，取代分散的 .nvmrc/.python-version/.tool-versions 文件，以及自动化 CI 流水线。

不适用场景： 仅使用容器的工作流（所有工具都在 Docker 镜像中），原生版本管理器已能很好满足需求的单语言项目，以及生产环境运行时管理（mise 是开发工具）。

版本解析顺序

Mise 按以下优先级检查这些来源，以解析工具版本：

1. MISE_<TOOL>_VERSION 环境变量
2. 当前目录中的 mise.toml
3. 父目录中的 mise.toml（沿目录树逐级向上查找）
4. .tool-versions 文件（兼容 asdf）
5. 旧版文件（.nvmrc、.python-version、.ruby-version）
6. ~/.config/mise/config.toml（全局默认值）

快速参考

模式	命令 / 配置	要点
安装工具	mise install	读取 mise.toml，安装其中列出的所有工具
固定工具版本	mise use node@22	写入当前目录下的 mise.toml
全局固定版本	mise use -g node@22	写入 ~/.config/mise/config.toml
运行任务	mise run build	运行 mise.toml 中定义的任务
带参数运行	mise run test -- --watch	将 -- 后的参数传递给任务
监视模式	mise watch build	源文件变更时重新运行任务
列出任务	mise tasks	显示所有可用任务
设置环境变量	mise.toml 中的 [env] 部分	按目录设置，执行 cd 时自动激活
加载 .env 文件	_.file = ".env"	将 dotenv 加载到环境中
扩展 PATH	_.path = ["./bin"]	将目录添加到 PATH 前面
列出已安装工具	mise ls	显示所有已安装的工具版本
过期工具	mise outdated	显示有更新版本的工具
升级工具	mise upgrade	在约束范围内将工具升级到最新版本
信任配置	mise trust	信任当前目录下的 mise.toml
工具后端	"npm:prettier" / "cargo:cargo-machete"	从 npm、cargo、pipx、GitHub 等安装
任务依赖	depends = ["lint", "test"]	先运行前置任务
增量构建	任务上的 sources + outputs	如果输出比源文件新，则跳过任务
未激活时执行	mise exec -- node app.js	使用 mise 管理的工具运行命令
诊断	mise doctor	检查安装和配置状态
清理未使用工具	mise prune	移除所有配置中都未使用的工具版本
生成钩子	mise generate git-pre-commit	为任务生成 git pre-commit 钩子
环境专属配置	.mise.staging.toml	通过 MISE_ENV=staging 激活
IDE 的 Shims	mise settings set shims_on_path true	基于 PATH 的 Shims，确保与 IDE 兼容

常见错误

错误	正确做法
使用 mise install node@22，却不使用 mise use	mise use node@22 会同时安装并固定版本到 mise.toml
使用 mise 时手动编辑 .tool-versions	使用 mise use 更新；优先使用 mise.toml，而非 .tool-versions
克隆新项目后忘记运行 mise trust	运行 mise trust 以激活不受信任的配置文件
使用 depends 键设置任务依赖	当前使用的键是 depends（数组），而不是 deps
未激活 mise 就运行 mise run	在 shell 配置文件中运行 mise activate，或使用 mise exec
将密钥直接放在 mise.toml 中	使用 _.file = ".env.local"，并将 .env 文件加入 gitignore
期望无需 cd 进入项目目录就能获得环境变量	Mise 会在目录变更时激活环境；使用 mise env 进行调试
在共享项目中使用 latest 版本	固定具体的主版本（node = "22"），以确保可复现性
在 Makefile 中定义任务，同时又使用 mise	将所有任务集中到 mise.toml 中，统一使用一个工具
多行任务脚本缺少 shebang	添加 #!/usr/bin/env bash，明确指定解释器
慢速任务未使用 sources/outputs	定义源文件 glob，以支持增量跳过和监视模式
在非交互式脚本中使用 mise activate	在脚本和 CI 中使用 mise exec 或 eval "$(mise env)"

委派

• 任务模式发现：使用 Explore Agent
• 配置审查：使用 Task Agent
• CI 流水线集成：使用 Task Agent

如果有 rust skill，请将 Rust 工具链管理模式委派给它。 如果有 python-uv skill，请将 Python 版本和虚拟环境模式委派给它。 如果有 github-actions skill，请将 CI 工作流模式委派给它。 如果有 docker skill，请将容器化工作流模式委派给它。 如果有 pino-logging skill，请将日志配置模式委派给它。 如果有 sentry skill，请将错误监控设置模式委派给它。

参考资料

• 工具版本管理和后端
• 任务定义、依赖项和脚本
• 环境变量和 dotenv 集成
• 配置文件和设置
• 项目常见任务模式
• 从 asdf、nvm 及其他方案迁移