mise

mise 工具链管理

概述

mise 可管理开发工具版本、环境配置和项目任务。使用它可确保团队成员和 CI 使用一致的工具链，并可与工具链一起定义构建、测试和部署工作流。

核心原则： 两种模式——对于你控制的仓库，使用 mise.toml（提交到仓库）；对于你参与贡献的仓库，使用 mise.local.toml（由 git 忽略）。

快速参考 - 加载内容

如果你要……	加载
在现有项目中采用 mise	改用 mise:onboard-project 技能
设置 mise.toml、了解优先级	references/configuration.md
定义任务、运行构建、使用监视模式	references/tasks.md
声明特定任务所需的工具	references/tasks.md
在单体仓库的各个包之间组织任务	references/monorepo-tasks.md
将扁平任务文件拆分为按组件定义的配置	references/monorepo-tasks.md
遇到“找不到命令”或激活问题	references/troubleshooting.md
设置 GitHub Actions、锁文件	references/ci-cd.md

何时使用各配置文件

场景	配置文件	是否提交？
你自己的项目、团队共用的工具	mise.toml	是
为他人的仓库贡献代码	mise.local.toml	否（由 git 忽略）
用户级默认配置	~/.config/mise/config.toml	不适用

核心原则

使用 mise.toml 进行团队配置： 如果你控制该仓库，请使用 mise.toml 定义项目所需的工具链，并将其提交到仓库。所有人都会获得相同的版本。

使用 mise.local.toml 配置个人工具： 为你无法控制的仓库贡献代码时，请使用 mise.local.toml 设置个人工具偏好。按照惯例，该文件会被 git 忽略。

始终运行 mise install： 克隆包含 mise.toml 的项目后，运行 mise install 来安装所需工具。此操作不会自动执行。

优先使用激活而非垫片： 在 shell rc 文件中使用 mise activate，以获得完整的功能支持。垫片也能使用，但有局限（除非调用工具，否则不会更新环境变量）。

提交 mise.lock 以确保可复现性： 锁文件可确保所有人获得完全相同的工具版本，并避免遇到速率限制问题。

停止——反合理化对照表

在编写符合以下模式的代码之前，请停止并重新考虑。

你正准备……	常见的合理化理由	应该怎么做
在 CI 脚本中添加 mise activate	“它在本地能运行”	CI 是非交互式的。使用 mise x -- command 或 shims。加载 references/ci-cd.md。
不将 mise.lock 纳入仓库	“我们用的是 ‘latest’”	“latest”会变。提交锁定文件以确保可复现性。加载 references/ci-cd.md。
因速率限制而从 CI 中移除 mise	“它阻碍了部署”	设置 GITHUB_TOKEN 以获得更高的限制。移除 mise 只会把问题转移到别处。加载 references/troubleshooting.md。
提交 mise.local.toml	“团队成员也应该使用这些工具”	这正是 mise.toml 的用途。本地文件属于个人。
使用 .bash_profile 激活	“我把 PATH 放在这里”	激活只适用于 .bashrc/.zshrc。加载 references/troubleshooting.md。
到处固定精确的补丁版本	“这样可最大限度地确保可复现性”	改用 mise.lock。在配置中固定版本会让更新变得繁琐。
将仅有一个任务需要的工具添加到项目 [tools] 中	“这样更简单” / “大家可能都会用”	将其放到 tasks.<name>.tools 中。永远不会运行该任务的贡献者就能跳过安装。加载 references/tasks.md。
将所有任务都放进多包项目的根 mise.toml 中	“这样更简单” / “只需检查一个文件”	每个包都应在自己的 mise.toml 中管理任务。根目录负责协调。加载 references/monorepo-tasks.md。
在中间层组配置中定义 task_templates	“模板应该放在使用它们的包附近”	模板只能从根 mise.toml 中解析。将所有模板移到根目录。加载 references/monorepo-tasks.md。
在 usage 字段中使用 TOML 数组语法（choices=["a","b"]）	“这是 TOML 文件”	usage 内容使用的是 KDL，不是 TOML。在代码块中使用 choices "a" "b"。加载 references/tasks.md。
在 { task = "...", env = {...} } 委托中传递 env	“依赖项支持这样做”	委托对象只支持 task/tasks 键。使用内联参数或任务级 env。加载 references/tasks.md。

常见工具配置

Rust

[tools]
rust = { version = "latest", components = "clippy,rustfmt" }
"cargo:cargo-nextest" = "latest"
"cargo:cargo-watch" = "latest"

Node.js

[tools]
node = "lts"
"npm:pnpm" = "latest"

Python

[tools]
python = "3.12"
"pipx:poetry" = "latest"

常见错误

错误	修复方法
提交 mise.local.toml	将其添加到 .gitignore
在自己的仓库中使用 mise.local.toml	使用 mise.toml，让贡献者也能受益
克隆后忘记运行 mise install	将其写入项目设置文档
CI 中缺少 GITHUB_TOKEN	设置令牌以应对 API 速率限制
在 .bash_profile 中激活	改用 .bashrc 或 .zshrc

权威资源

• mise 文档
• 配置参考
• 任务运行器
• 任务配置
• Monorepo 任务（实验性）
• CI/CD 集成