mise 使用指南：全局与项目级工具版本

mise 是 asdf 系的多语言版本管理器：一份 TOML 声明工具与版本，进目录自动切换，脚本里用 mise exec 固定环境。我把它和 dotfiles 一起用，替代以前在 Homebrew / fnm / SDKMAN 之间拆版本的做法。机器级安装步骤见 macOS 开发环境配置。

装什么、装在哪

安装 mise：

curl -fsSL https://mise.run | sh

Shell 里启用（dotfiles 已在 ~/.zshrc 末尾）：

eval "$(mise activate zsh)"

首次或改配置后：

mise install

我的全局配置摘要

[tool_alias]
pnpm = "npm:pnpm"

[tools]
java = [
  "oracle-graalvm-25.0.5.0.3",
  "oracle-graalvm-21.0.12.1.1",
  "oracle-graalvm-17.0.12",
  "temurin-27",
  "zulu-8",
]
maven = "3.10.0"
gradle = "latest"
spring-boot = "4.1.0"
python = "3.13.16"
node = "26.9.0"
pnpm = "12.17.0"
pipx = "1.18.3"

要点：

• Java 数组：第一项是默认 java（当前 GraalVM 25）；其余用 mise shell java@… 或别名临时切换。
• pnpm = "npm:pnpm"：本机 aqua 发布的 pnpm 包解压失败时，改走 npm 后端；写版本仍用 pnpm = "12.17.0"，需要旧主版本时用 mise exec npm:pnpm@10.34.9 -- pnpm …。
• Spring Boot CLI：在 [plugins] 里 pin 社区 asdf 插件 URL（见 dotfiles 完整文件）。

常用命令

mise ls                 # 已安装版本
mise ls --current       # 当前目录生效版本
mise where node         # 解析后的安装路径
mise install            # 按 config + mise.toml 补缺
mise install node@26.9.0   # 只装某一工具

单次命令（不污染当前 shell，适合 CI 脚本）：

mise exec -- pnpm install
mise exec npm:pnpm@8.15.9 -- pnpm --dir ~/github/running_page install
mise exec -- ./mvnw test

当前 shell 临时改版本（关掉终端或 mise shell --unset java 失效）：

mise shell java@oracle-graalvm-21
mise shell node@26.13.0

dotfiles 里别名：j8 / j17 / j21 / j25 / j27 对应 mise shell java@…。

项目级 mise.toml

进目录后，mise 合并全局 config + 项目 mise.toml，项目优先。

示例：

# 博客仓库：只 pin 前端栈
[tools]
node = "26.13.0"
pnpm = "12.16.1"

# Java 演示项目：编译目标 21
[tools]
java = "oracle-graalvm-21"
maven = "3.10.0"

# 老前端：pnpm 8 主版本
[tools]
python = "3.13.16"
node = "26.9.0"
pnpm = "8.15.9"

cd 进目录后执行 mise ls --current，确认 node/java/pnpm 来源列指向该项目的 mise.toml。

与 Corepack / GitHub Actions 一起用时：package.json 的 packageManager、本地 mise.toml、CI 里的 pnpm/action-setup 版本应一致，避免「本地能装、CI 锁文件不过」。

任务（tasks）

部分仓库在 mise.toml 里定义 [tasks]，例如：

mise run test
mise tasks ls

带 secrets 或非纯版本字段的配置可能需要 mise trust。日常只读 [tools] 时通常不必 trust。

维护

Homebrew 仍装 git、gh、Ghostty 等；不要再用 Brew 装 Node/Python/pnpm，以免和 mise 的 PATH 抢优先级。

排错

• pnpm 版本不对：看 mise ls --current；是否被项目 mise.toml 覆盖；是否应用了 tool_alias 后应用 npm:pnpm@版本 执行。
• Java 版本不对：确认 java = [...] 第一项；或项目 mise.toml 是否写了 java = "oracle-graalvm-17" 等。
• 进目录没切换：是否 mise activate zsh；新开终端是否加载了 ~/.zshrc。
• aqua 装 pnpm 失败：在全局加 [tool_alias] pnpm = "npm:pnpm"（见上文）。

参考

• mise 官方文档
• dotfiles / mise/config.toml
• macOS 开发环境配置