mise

mise

mise 是此技能适用项目唯一允许使用的运行时和工具管理器。 每个项目都会在仓库根目录的 mise.toml 中固定所有工具， 将解析后的版本记录在已提交的 mise.lock 中， 并将依赖关系图记录在已提交的 .mise/locks/ 中， 禁用 ubi 和 asdf 后端， 通过 pypi: 安装 Python CLI，通过 npm 安装 Node CLI， 其他所有工具则使用 aqua（或 mise 内置的 core）。

硬性规则

1. mise 是唯一的管理器。 不得使用 brew install、 nvm、 asdf、 volta、 fnm、 pyenv、 rbenv、 tfenv、 goenv、 用于安装 CLI 的 pip、pipx 或 uv tool， 临时安装程序， 或 curl 管道脚本。

2. 每个 mise.toml 都必须包含以下 [settings] 区块：

   [settings]
   disable_backends = ["ubi", "asdf"]
   lockfile = true
   

   disable_backends 会从整个项目的解析链中移除 ubi 和 asdf； core 运行时（go、node、python 等）不受影响，因为 mise 会保留它们对应的 aqua 和 core 条目。 lockfile = true 会让 mise 读取和写入 mise.lock。

3. 每种工具对应的后端：

   • Python CLI（例如 black、ruff、poetry）→ pypi: — 每个 CLI 都有独立的锁定依赖关系图、 独立的 venv， 以及独立的私有 Python， 因此不会意外使用由 aqua 捆绑的 Python （参见下文的 Python CLI：完全隔离）。 pipx: 是同一后端的另一种名称，并未弃用， 因此现有条目可在遵循相同规则的前提下继续使用； 新条目请使用 pypi:。 mise 会将 pipx:x 和 pypi:x 视为不同工具： 更改前缀意味着需要重新安装，并新增一条锁定记录。
   • Node／JS CLI（例如 typescript、prettier、eslint）→ npm: — mise 的 npm 后端会通过 mise 管理的 Node 安装， 因此不会意外使用由 aqua 捆绑的 Node。
   • 其他所有工具 （运行时、terraform、kubectl 等单二进制文件 CLI）→ 裸名称， 由 mise 解析为 aqua 或 core。
   • 不在 aqua 中的 Rust CLI → cargo:。 不在 aqua 中的 Ruby CLI → gem:。
   • 不得使用 ubi 和 asdf（参见规则 2）。

4. 版本必须完全固定。 不得使用 latest、 lts、 仅指定主版本（20）、 仅指定次版本（20.11）。 始终使用完整版本号（20.11.1、1.22.4、1.7.5）。 mise.lock 和 .mise/locks/ 必须与 mise.toml 一并提交。

5. 项目配置文件是仓库根目录下的 mise.toml。 不得使用 .mise.toml、 .tool-versions、 .nvmrc、 .python-version、 .ruby-version。 如果 .mise.toml 已存在， 不要直接修改它 — 请执行迁移流程。

6. 仅涵盖 [tools] 和 [settings] 部分， 以及 [env] 中的 Python 保护区块和 venv 条目（见下文）。 其他 [env] 条目、 [tasks]， 以及其他部分 — 请另行处理。

7. 仅限本地设置。 本技能不涵盖 CI 集成。

8. mise.lock 和 .mise/locks/ 均由 mise 生成，绝不可手动编辑。 只有 mise 命令可以写入这些文件 — 通常使用 mise lock。 绝不要手动或使用任何非 mise 工具创建、编辑或修补这些文件： 无论是版本号、 校验和、 平台条目， 还是依赖关系图。 如需更改锁文件记录的内容， 请编辑 mise.toml 并运行 mise lock； 锁文件会随之更新。

Python CLI：彻底隔离

Python 包只会安装到一个确切的解释器中， 并由同一个解释器运行。 “安装在一个 Python 中，却用另一个 Python 运行，结果找不到包” 这种情况必须不可能发生。 这需要 mise 2026.10.24 或更高版本； 如果 mise --version 显示的版本较旧， 请先让用户升级。

每个 pypi: 条目都要指定其 Python， 并在旁边固定 uv 版本：

[tools]
uv = "0.13.6"
"pypi:black" = { version = "24.4.2", python = "3.14.10" }

这样，每个工具都会拥有：

• 专用解释器。 python 选项接受完整版本号。 mise 会安装此运行时，但不会将其加入 shell 的 PATH， 而且 [tools] 中的 python 固定版本无法让工具脱离它。 如果没有此选项，工具会使用项目的 python， 并随其每次升级而切换， 或使用 PATH 中的第一个 Python， 或者在该 Python 不符合包的要求时， 使用 uv 为自身下载的 CPython。
• 独立的 venv， 路径为 installs/pypi-<tool>/<version>~uv~<hash>/， 禁用系统和用户 site-packages，且内部不含 pip。 只有工具的命令会进入 PATH， venv 中的 python 绝不会进入。 锁定相同依赖关系的仓库会共用一个 venv。
• 锁定的依赖关系。 mise lock 会将 pyproject.toml 和 uv.lock 写入 .mise/locks/pypi-<tool>/<version>~<hash>/， 并为每个 wheel 记录哈希值， 同时在 mise.lock 中记录路径和摘要。 使用 --locked 安装时，会通过 uv sync --frozen --no-build 重现这些依赖： 仅使用 wheel， 因此安装时不会运行任何包代码。

uv 负责锁定和安装这些工具。 0.12.10 是能够锁定依赖关系的最低版本， 并非推荐使用的版本： 0.13.4 之前的版本存在已知安全公告， 因此请固定一个当前版本。 [settings] 中的 pipx.uvx = true 已废弃 — 安装 uv 后，它本来就是默认安装程序 — 所以看到就删掉。 仅当项目本身运行 Python 时，才在 [tools] 中固定 python； 这些工具不需要它。

防护块

任何包含 pypi: 工具或 python 固定版本的 mise.toml 也必须包含此代码块， 这是规则 6 的例外：

[env]
PYTHONPATH = false               # would shadow a tool's own packages
PYTHONHOME = false               # would redirect or break the interpreter
PIP_REQUIRE_VIRTUALENV = "true"  # pip refuses to install outside a venv
UV_PYTHON_DOWNLOADS = "never"    # uv cannot fetch a CPython of its own

venv 无法阻止 PYTHONPATH： 在该路径中找到的包会接管工具的导入。 误用 pip install 会将包安装到 该 Python 上所有项目共用的运行时中。 mise 会在已激活的 shell 中、 mise x 中以及通过 shims 应用此代码块； 只有通过完整安装路径启动的工具不受其影响。

保持工具隔离

• 通过工具命令运行工具（black）， 不使用包装器，且绝不要使用 python -m black。 shell 的 python 没有该包，而且就应该没有： 它报出 No module named black 表明隔离机制正在生效， 不应该通过再次安装该包来修复。

• 绝不手动安装。 不要对 CLI 使用 pip install、 uv pip install、 pipx install 或 uv tool install， 也不要向工具的 venv 中安装任何内容。 插件通过工具的 with 选项添加， 拥有独立命令的配套工具通过 expose 添加； 两者都要使用 == 固定版本，并与工具一同锁定：

  "pypi:ansible-core" = { version = "2.21.5", python = "3.14.10", expose = ["ansible-lint==26.9.0"] }
  

• 不要使用 uvx_args 或 pipx_args。 它们无法锁定： 工具只会得到一个仅含版本号的条目， --locked 安装会拒绝该条目。 应改用 python、with 和 expose。

• 项目自身代码导入的库不是工具。 pypi: 不会让任何内容可供导入； 请参阅下文的 使用 Python 编写的项目。

查看工具实际使用的 Python：

grep -E '^(home|version_info)' "$(mise where pypi:<tool>)/.mise-uv/.venv/pyvenv.cfg"

home 必须是 installs/python/<the pinned version>/bin。 没有此类文件，说明该工具并非从依赖关系图安装。 如果 PATH 中有 shims， command -v python3 会显示 shim 的路径， 即使它最终使用的是另一个 Python； 请改为运行 python3 -c 'import sys; print(sys.executable)'。

使用 Python 编写的项目

固定 python 版本，并让 mise 保持项目的虚拟环境处于激活状态：

[tools]
python = "3.14.10"

[env]
_.python.venv = { path = ".venv", create = true }

在已运行 mise activate 的终端中， python script.py 随后会在该虚拟环境中运行，无需包装命令， 而 mise 会在首次使用时创建虚拟环境。 如果项目中没有 uv， pip 也属于该虚拟环境， 所以 pip install 会将包安装到 python 查找的位置。 如果项目中有 uv，虚拟环境中就没有 pip： 在 pyproject.toml 中声明包，然后运行 uv sync。 同一项目中的 pypi: 工具会使用自己的 Python 和虚拟环境。 将 .venv/ 添加到 .gitignore。

仅使用 Shims 不会激活虚拟环境， 因此，未运行 mise activate 的 Shell（例如 Agent 的 Shell） 会在运行 python 时提示 No module named …； 请在此类环境中调用 .venv/bin/python。

项目与机器

项目彼此不可见： 每个项目只会获取自身 mise.toml 中的工具， 两个项目可以固定同一工具的不同版本和 Python 版本。

机器的全局配置会按预期继承： 其中的工具（例如 docker）在每个项目中都可用， 项目中的条目会覆盖全局条目。 这不会削弱上述隔离： 全局 Python CLI 和其他工具一样有自己的虚拟环境， 而全局 python 无法更改指定了自身版本的工具。 它只会决定在未固定版本的项目中 python3 指向什么， 因此不要将 python 本身放入全局配置。 父目录中的 mise.toml 也会以同样的方式继承； 对于必须独立运行的项目，其上层目录中不要放置此类文件。

mise lock 未生成依赖图时

即使无法写入依赖图，mise lock 也会以 0 退出， 因此它的退出代码无法证明任何事情。 mise.lock 中已锁定的条目会包含一行 uv：

[[tools."pypi:black"]]
version = "24.4.2"
backend = "pypi:black"
specifiers = ["24.4.2"]
uv = { path = ".mise/locks/pypi-black/24.4.2~87de8a48", digest = "sha256:…" }

如果条目中只有 version、backend 和 specifiers，则没有依赖图。 mise lock 的输出会说明原因：

输出包含	原因	解决方法
uv >= 0.12.10 is unavailable	尚未安装 uv	执行锁定并安装中的第 1 步，然后重新锁定
Python dependency locks require uv >= 0.12.10	固定的 uv 版本太旧	固定一个当前版本的 uv
No interpreter found	未设置 python 选项，或未安装对应的运行时	添加该选项，执行锁定并安装中的第 1 步，然后重新锁定
has no usable wheels	某个依赖没有适用于该 Python 版本的 Wheel	降低 Python 版本（见下文）
uvx_args or pipx_args	无法锁定这些选项	将它们替换为 python、with、expose
exclude-newer	某个版本的发布时间早于 minimum_release_age（默认 24 小时）	等待，或固定一个更旧的版本
uses lockfile format version	锁文件版本较旧；格式 0 和 1 不包含依赖图	mise lock --upgrade

全新的 Python 版本通常会导致 has no usable wheels： 依赖图只会安装 Wheel， 因此每个依赖都必须为该解释器发布一个 Wheel。 例如，PyYAML 6.0.3 发布的 Wheel 最高支持 cp314， 因此 cookiecutter 2.7.1 使用 Python 3.14.10，而不是 3.15.2。 切勿通过允许从源码构建来解决此问题。 选择整个依赖图都有 Wheel 支持的最新 Python 版本 （mise latest [email protected] 会解析出一个次版本系列）， 并在工具旁记录原因：

# 3.14, not 3.15: PyYAML 6.0.3 ships no cp315 wheels.
"pypi:cookiecutter" = { version = "2.7.1", python = "3.14.10" }

确认 mise 将执行的操作

运行 mise registry <tool>，查看 mise 对某个工具使用的后端链。 禁用 ubi 和 asdf 后， mise 会继续使用链中的下一个条目 （通常是 aqua 或 core）。 如果没有剩余条目， mise 会拒绝安装 — 这是预期且可见的失败， 也是触发下文 工具不可用 流程的信号。

操作前先确认

如果以下任一事项不明确，请询问用户：

• 要固定哪个确切版本 — 切勿自行编造， 也不要写 latest；
• 当 pypi 和 npm 都不适用且 aqua 中没有该工具时，要使用哪个后端；
• 项目自身的代码是否依赖 PYTHONPATH — 保护代码块会取消设置该变量；
• 迁移时是否删除旧版配置文件 （.nvmrc、.tool-versions、Brewfile 等）；
• 是否要为 asdf 破例 — 请参阅下文的 工具不可用。

如果无法连接网络来确定“最新”版本， 请向用户询问确切版本，而不要猜测。

根据文档核对记忆

mise 会在不同版本之间更改设置、注册表条目和后端行为。 如果此处的任何内容 — 后端语法、设置键、注册表内容、信任行为、锁文件语义 — 看起来陌生或过时， 请在编写配置或运行命令前前往 https://mise.jdx.dev/ 核实。 不要猜测。

流程：锁定并安装

其他流程都在此结束。 mise lock 不会运行任何包代码， 因此问题会在安装任何内容之前显现。

1. 如果 [tools] 中有 pypi: 工具， 请安装锁定所需的内容： uv，以及每个不同 python 选项对应一个 python@<version>。

   mise install uv [email protected]
   

   没有 uv，mise lock 就不会记录依赖图。 没有运行时，就没有可供解析的解释器。 此处出现 WARN python installed but not activated 是预期情况： 该运行时仅供该工具私下使用。

2. 写入锁文件和依赖图：

   mise lock
   

   如果出现锁文件使用较旧格式的警告， 请运行 mise lock --upgrade。

3. 检查 mise.lock 中每个 pypi: 条目是否都有 uv 行。 如果有任何一项缺少， 请停止并修复原因（请参阅 mise lock 未生成依赖图时）。

4. 严格安装：

   MISE_IGNORED_CONFIG_PATHS="$HOME/.config/mise" mise install --locked
   

   该变量可让机器上的全局工具不受这条命令影响： --locked 会要求这些工具也有锁定条目， 否则就会因 is not in the lockfile 而失败。 它们仍会像往常一样在项目中可用。 遇到缺失的依赖图、缺失的旁文件或已编辑的依赖图时，--locked 会失败。 普通的 mise install 不会： 没有可用的依赖图时，它会退回到 uv tool install， 重新解析依赖，并可能构建源码分发包， 从而运行其中的代码。 它也会接受已编辑的依赖图并重写摘要。 mise x 也会以普通方式安装缺失的工具， 因此请在启动任何工具之前运行此命令。

5. 使用 mise ls 验证。 没有关联配置文件的 python 行，表示这是工具的私有运行时。

6. 提交 mise.toml、mise.lock 和 .mise/locks/。 不得将 .mise/locks/ 加入 Git 忽略列表： 全新克隆需要它来执行第 4 步的严格安装， 在运行 mise trust 后，这是该克隆唯一需要运行的步骤。

普通的 mise lock 会复用已记录的依赖图。 若要为版本未变的工具获取依赖修复， 请运行 mise lock --bump pypi:<tool>， 然后执行第 4 步的严格安装。

流程：新项目设置

1. 确认不存在现有的 mise.toml 或 .mise.toml。 如果 .mise.toml 存在， 请停止并运行迁移流程。

2. 在仓库根目录创建 mise.toml：

   [settings]
   disable_backends = ["ubi", "asdf"]
   lockfile = true
   
   [tools]
   

3. 对于项目使用的每个运行时和 CLI， 确定完整版本 （如果未指定，请询问用户）， 并按照 各工具的后端 规则添加条目。 示例：

   [tools]
   node      = "20.11.1"
   go        = "1.22.4"
   terraform = "1.7.5"
   uv        = "0.13.6"
   "pypi:black"     = { version = "24.4.2", python = "3.14.10" }
   "npm:typescript" = "5.4.5"
   

   如果使用了 pypi: 工具或固定了 python 版本， 请添加 Python CLI：完全隔离 中的保护代码块。 使用 Python 编写的项目还需添加 Python 编写的项目 中的 venv 条目。

4. 运行 mise trust 以授权该文件。

5. 运行 流程：锁定并安装。

流程：添加或固定工具版本

1. 确认仓库根目录下存在 mise.toml，且其中包含所需的 [settings] 块。 如果缺少 [settings] 或内容不完整， 请添加。
2. 确定要固定的确切版本 （如果未指定，请询问）。
3. 根据 按工具选择后端 规则选择后端。 如果不确定 mise 会选择哪个后端，请运行 mise registry <tool>。
4. 在 [tools] 下添加条目。 pypi: 工具须遵循 Python CLI：完全隔离： 设置 python 选项、 固定 uv 版本， 并保留防护块。 用 Python 编写的项目中的 python 固定版本须遵循 用 Python 编写的项目。
5. 运行 mise trust。 在普通模式下，信任状态按路径持久保存； 在 paranoid 模式下，mise 会对文件进行哈希处理，每次修改后都必须重新信任—— 每次写入后运行 mise trust，即可安全地兼顾这两种模式。
6. 运行 流程：锁定并安装。

流程：从其他管理器迁移

出现以下任一情况时触发： .mise.toml、 .nvmrc、 .tool-versions、 .python-version、 .ruby-version、 包含运行时或 CLI 工具的 Brewfile、 volta 或 fnm 配置、 mise.toml 中的 pipx.uvx、uvx_args 或 pipx_args、 README 中类似 nvm install … 的行、 brew install <runtime>， 或 pipx install …。

1. 列出由其他系统管理的所有工具， 并将任何版本范围或 latest 标记解析为具体的固定版本。
2. 向用户提供迁移计划： 拟定的 mise.toml（含 [settings] 和 [tools]）、 将要删除的文件、 需要改写的文档行。 对于现有的 .mise.toml： 建议将其重命名为 mise.toml，并添加所需的 [settings] 块—— 不要直接修改 .mise.toml。 对于使用 uvx_args 或 pipx_args 的 Python CLI： 建议采用 Python CLI：完全隔离 中的条目， 并移除 pipx.uvx。
3. 等待用户明确确认后再进行更改。
4. 确认后： 写入 mise.toml， 删除过时的配置文件， 更新文档，使其引用 锁定并安装 中的严格安装流程。
5. 运行 mise trust， 然后运行 流程：锁定并安装， 并一并提交删除操作。 mise prune --yes pipx:<tool> 可移除因前缀变更而遗留的安装。

流程：任何允许的后端都不提供该工具

如果 mise registry <tool> 只显示 ubi 或 asdf， 或者完全没有显示内容：

1. 停止。
2. 向用户说明情况： 工具名称、 mise 列出的后端、 项目中禁用 ubi 和 asdf 的策略。
3. 按以下顺序提供替代方案：
   • 选择另一个支持 aqua / core / pypi / npm / cargo / gem 选项的工具；
   • 如果工具的语言与某个语言原生后端匹配，则通过该后端安装 （pypi、npm、cargo、gem）；
   • 最后才询问用户是否批准从本项目的 disable_backends 中移除 asdf。
4. 如果用户批准覆盖 asdf 设置： 保持禁用 ubi， 写入工具条目， 并在条目上添加 TOML 注释，记录原因 （工具名称、检查过的其他后端，以及它们均不适用的原因）。 绝不要重新启用 ubi。

报告

完成更改后， 说明写入或更新了哪个 mise.toml， 添加或固定了哪些工具（含后端和版本）， 每个 pypi: 工具使用哪个 Python，以及其依赖关系图是否已锁定， 删除了哪些旧文件， mise.lock 的状态（已创建或已刷新）， 以及用户接下来应运行的命令 （mise trust、锁定并安装 中的严格安装命令、mise ls）。