mise 的 not_found_auto_install 自动安装不触发时怎么排查？

mise 的 not_found_auto_install 自动安装不触发时怎么排查？

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise

在 shell 里输入一条命令，提示 command not found，而 mise 本应通过not_found_auto_install自动装上对应工具却没有反应——这是 docs/troubleshooting.md 中记录的典型症状之一。not_found_auto_install（默认值为true）是 mise 的 Command Not Found Handler：当命令在 shell 中找不到、且 handler 已启用时，mise 会用注册表（registry）中的bins元数据把命令映射回提供它的工具并自动安装。这个机制依赖 mise 的 shell 集成（shell integration），并且只对当前目录配置里已经声明过的工具生效。下面按文档给出的三类原因逐项排查。

先确认设置当前是否为启用状态

handler 的开关是not_found_auto_install，另外还有一个按工具屏蔽它的auto_install_disable_tools（工具名列表）。用文档 docs/configuration/settings.md 给出的命令检查生效值：

# 查看所有生效的设置，包括默认值 mise settings ls --all # 额外显示每个已配置值的来源（哪个文件设置成了 false） mise settings ls --json-extended

--all用来确认not_found_auto_install的生效值，--json-extended用来定位是哪一层配置（全局还是项目级）把它设成了false。如果确认是关闭状态，按文档的写法重新打开：

mise settings set not_found_auto_install true # 写入全局配置 mise settings set --local not_found_auto_install true # 写入当前项目配置

打开后重启 shell 再验证。最后还要检查auto_install_disable_tools：即使总开关是开着的，工具名出现在这个列表里时，该工具的自动安装依然不会触发。

检查工具是怎么声明的：注册表名还是 raw backend spec

docs/troubleshooting.md 列出的前两个原因都与"当前目录配置"有关：

1. 工具根本没有配置。handler 只会安装当前目录配置里已经要求过的工具；对一条你从未声明过的命令，它不会替你挑选工具。也就是说，在没有任何配置声明对应工具时输入命令，自动安装不会发生。

2. 工具是用 raw backend spec 配置的。例如：

   [tools] "cargo:some-crate" = "1.0.0" "github:owner/repo" = "1.0.0"

   raw backend spec 不是注册表条目，不携带bins元数据，因此没有任何东西能把你在 shell 里敲的命令和它关联起来。docs/dev-tools/index.md 的 "Command Not Found Handler (Shell Integration)" 一节同样强调了这一限制。

对应的处理：只要注册表里有该工具的条目，就用注册表名声明它，而不是 raw backend spec——文档给的例子是写ripgrep而不是github:BurntSushi/ripgrep，这样 handler 才能把命令映射到工具。

注意一个容易混淆的点：注册表名声明的工具即使从未安装过，handler 也能处理（bins元数据来自注册表，不依赖已安装的版本）；只有 raw backend spec 这一类才有映射问题。

确认 shell 集成确实生效

该 handler 属于 shell 集成的一部分：mise activate会安装 shell hooks，由它们在 prompt 前后刷新环境并响应 command-not-found。因此要确认两点：

• 普通的mise activate（如eval "$(mise activate bash)"）应放在交互式 shell 的 rc 文件（如~/.bashrc、~/.zshrc）中。docs/troubleshooting.md 开头一节说明：profile 或非交互脚本可能根本不会执行这些 hooks；如果mise activate放错了位置，相关 hook 不会运行。
• 对脚本或 CI 场景，非交互 shell 里不依赖 shell hook，文档建议改用mise exec -- command（或mise run task）来显式选择环境；shims 是命令需要通过PATH解析工具时的另一个选项。

替代路径：显式安装，装过一次后 handler 即恢复可用

如果工具确实只能以 raw backend spec 声明，或者你不想依赖自动安装，文档给出的 workaround 是显式安装：

mise install # 安装当前配置中的工具 mise x <command> # mise x|exec：一步完成"安装 + 运行"

mise install和mise x/exec都会把整个已配置的工具集落到磁盘，因此 backend 形式（注册表名或 raw spec）不再影响安装；mise r|run同理，但只在运行任务时顺带完成。

还有一点值得记住：文档明确说，手工装过一次就够——只要本地存在该工具的版本，mise 也可以从已安装的可执行文件中发现命令到工具的映射，handler 从那时起就能工作了。

边界：关闭自动安装后，shim 会静默回退到系统二进制

docs/dev-tools/shims.md 记录了一个相关边界：当某个 shim 无法解析到 mise 管理的工具（例如mise.toml里固定了版本但尚未安装，且not_found_auto_install已关闭）时，它不会直接报错，而是回退到PATH上第一个同名可执行文件。对系统自带的工具（如 Debian/Ubuntu 上的python3），这可能意味着静默运行了一个完全不同的二进制。如果你希望无法解析的 shim 直接失败，文档建议同时设置：

mise settings set not_found_system_fallback false # 配合 not_found_auto_install = false 使用

排查小结

按 docs/troubleshooting.md 的顺序核对即可：先确认not_found_auto_install生效值与auto_install_disable_tools（mise settings ls --all/--json-extended），再看当前目录的工具声明是注册表名还是 raw backend spec、是否压根没声明，最后确认 shell 集成（mise activate）在交互式 shell 中确实生效。任一项不满足都会让 handler 静默不触发；确认声明方式无法改为注册表名时，直接用mise install或mise x显式安装，装过一次后 handler 即可正常工作。

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise