working-with-mise

使用 mise

概述

mise 是一款多语言工具版本管理器。在以下情况下使用此技能：

• 通过 mise 为项目添加工具
• 排查 mise 应该已提供工具，但却出现“找不到命令”的问题
• 判断 mise 是否适合用于某个依赖项

铁律

1. 使用 mise use 添加工具——绝不手动编辑配置文件
2. 先检测现有配置文件——如果已有配置文件，就不要新建
3. 修复 shell，不要绕过问题——如果工具不在 PATH 中，应诊断激活问题，而不是永久使用 mise exec 作为变通方法

何时使用 mise，何时选择替代方案

版本对项目而言很重要时使用 mise

不同项目需要不同版本的工具：

• 语言运行时：node、python、ruby、go、rust
• 基础设施工具：terraform、kubectl、helm
• 不同版本之间存在重大变更的工具

# Good mise candidates - version sensitivity
mise use node@20      # Projects may need different Node versions
mise use [email protected]  # IaC often pins specific versions
mise use [email protected]     # Gemfiles often require specific Ruby

版本很少影响使用时使用 Homebrew/系统工具

不同版本间接口一致的稳定 CLI：

• jq、yq——查询语言稳定
• gh、hub——GitHub CLI
• ripgrep、fd——搜索工具
• tree、htop——系统实用工具

# Better as Homebrew - version doesn't matter
brew install jq gh ripgrep

决策清单

问问自己：

1. 这个项目的 README/文档是否指定了版本？→ mise
2. 团队成员是否可能需要不同版本？→ mise
3. 该工具的不同版本之间是否存在重大变更？→ mise
4. 这是否是一个在任何地方都以相同方式使用的稳定 CLI？→ Homebrew

使用 mise 添加工具

1. 先检查现有配置文件

添加工具之前，先检测项目使用的配置格式：

# Check for existing mise config
ls -la mise.toml .mise.toml .mise.local.toml .tool-versions 2>/dev/null

配置文件优先级（mise 使用它找到的第一个文件）：

• mise.toml 或 .mise.toml——标准 mise 配置
• .mise.local.toml——本地覆盖配置（通常被 gitignore 忽略）
• .tool-versions——旧版 asdf 格式

**如果配置文件已存在，就使用该格式。**不要新建配置文件。

2. 使用 mise use 添加工具

始终使用 CLI——它会验证工具是否存在且可用：

# Add to project config (mise.toml or existing format)
mise use node@20

# Add to global config (~/.config/mise/config.toml)
mise use -g [email protected]

# Dry run to see what would happen
mise use --dry-run [email protected]

绝不要手动编辑配置文件——mise use 可确保：

• 工具/版本存在于注册表中
• 工具能够正确安装
• 配置语法有效

3. 验证工具是否可用

# Check mise sees the tool
mise ls

# Check the tool is on PATH
which node
node --version

# Compare with mise's view
mise which node

排查“找不到命令”

当工具应该可用却找不到时：

诊断工作流

# 1. Check mise installation health
mise doctor

# 2. Check what tools mise knows about
mise ls                    # All installed tools
mise ls --current          # Tools for current directory

# 3. Compare which vs mise which
which node                 # What shell finds
mise which node            # What mise thinks it should be

# 4. Check if tool would work via mise exec
mise exec -- node --version  # If this works, it's an activation issue

常见原因与修复方法

未设置 Shell 激活

症状：mise exec -- node 可用，但 node 不可用

诊断：

mise doctor  # Look for activation warnings

修复——添加到 shell rc 文件：

# For zsh (~/.zshrc)
eval "$(mise activate zsh)"

# For bash (~/.bashrc)
eval "$(mise activate bash)"

# For fish (~/.config/fish/config.fish)
mise activate fish | source

然后重启 shell，或对 rc 文件执行 source。

配置文件未受信任

症状：mise 显示信任警告，工具未激活

修复：

mise trust

当前目录未安装该工具

症状：mise ls 显示工具已全局安装，但 mise ls --current 中没有

诊断：

# Check what config file applies
mise config

# Check if there's a local config overriding global
cat mise.toml .mise.toml .tool-versions 2>/dev/null

修复：将工具添加到项目配置中：

mise use node@20  # Adds to project config

Shims 与 PATH 激活混淆

症状：工具在终端中可用，但在 IDE/脚本中不可用

详细说明请参阅 references/dev-tools/shims-html.md。

非交互式环境的快速修复：

# In ~/.zprofile or ~/.bash_profile (non-interactive)
eval "$(mise activate zsh --shims)"

# In ~/.zshrc or ~/.bashrc (interactive)
eval "$(mise activate zsh)"

适合使用 mise exec 的情况

以下情况适合使用 mise exec：

• 使用指定版本运行一次性命令：mise exec node@18 -- npm test
• 无法进行激活的 CI/CD 脚本
• 临时测试其他版本

以下情况不应使用 mise exec 来解决：

• 终端中的工具未加入 PATH（应修复激活配置）
• 将“使用 mise exec 时可用”作为永久解决方案

排查 GitHub 401 / 令牌错误

症状：mise install 或 mise use 从 GitHub 获取工具时失败，并显示 401 Unauthorized。

高优先级来源中的过期令牌会悄无声息地覆盖所有优先级较低的来源。错误令牌比没有令牌更糟：GitHub 对无效凭据返回 401，而匿名请求则会成功（但受速率限制）。

1. 查找 mise 选用了哪个来源

mise token github    # masked output - safe to paste into logs
# github.com: gho_…tSoC (source: gh CLI (hosts.yml))

2. 令牌优先级——匹配到第一个就停止

1. MISE_GITHUB_TOKEN
2. GITHUB_API_TOKEN
3. GITHUB_TOKEN
4. github.credential_command
5. 原生 GitHub OAuth
6. ~/.config/mise/github_tokens.toml
7. gh CLI hosts.yml——默认启用，也是最常见的罪魁祸首
8. git credential fill——选择启用

这里有两个容易踩的坑：

• GH_TOKEN 不是 mise 的令牌来源。 它是 gh 自己的变量，所以导出它不会有任何影响。请使用 GITHUB_TOKEN 或 MISE_GITHUB_TOKEN。
• 空值等同于未设置。 GITHUB_TOKEN= mise install 会直接回退到 hosts.yml。这组环境变量中没有哪个能让 mise 匿名运行。

3. gh CLI 陷阱

mise 会直接读取 ~/.config/gh/hosts.yml——它从不调用 gh。因此，gh 自己的过期处理机制永远不会运行，过期的 oauth_token 会一直返回 401。

解决方法——重新进行身份验证：

gh auth login -h github.com

或者绕过 gh 集成——这比将 GH_CONFIG_DIR 指向空目录更简洁：

MISE_GITHUB_GH_CLI_TOKENS=0 mise install    # mise token github -> (none)

要永久生效，请在 ~/.config/mise/config.toml 中设置：

[settings.github]
gh_cli_tokens = false

关于 GitHub Enterprise、credential_command 和存储在密钥环中的令牌，请参阅 references/dev-tools/github-tokens-html.md。

验证命令

更改配置后，请验证一切正常：

# Full health check
mise doctor

# Verify specific tool
mise which node && node --version

# Verify PATH includes mise tools
echo $PATH | tr ':' '\n' | grep mise

可用参考资料

• references/cli/use-html.md - 完整的 mise use 文档
• references/cli/doctor-html.md - 诊断命令
• references/cli/activate-html.md - Shell 激活
• references/cli/which-html.md - 路径解析
• references/dev-tools/shims-html.md - Shims 与 PATH 激活
• references/dev-tools/github-tokens-html.md - GitHub 令牌来源及优先级
• references/guides/getting-started.md - 设置指南

危险信号——这些做法即将违规

• “我直接把这个手动添加到 mise.toml 里吧” → 改用 mise use
• “我用 mise exec 来绕过这个问题吧” → 诊断激活为何不起作用
• “我创建一个 .mise.toml 吧” → 先检查配置是否已存在
• 将 jq/gh/ripgrep 添加到 mise → 考虑是否真的需要指定版本
• 假定 mise 已激活 → 运行 mise doctor 进行验证
• 导出 GH_TOKEN 来修复 mise 401 错误 → mise 不会读取它；请先运行 mise token github