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 specdocs/troubleshooting.md 列出的前两个原因都与当前目录配置有关工具根本没有配置。handler 只会安装当前目录配置里已经要求过的工具对一条你从未声明过的命令它不会替你挑选工具。也就是说在没有任何配置声明对应工具时输入命令自动安装不会发生。工具是用 raw backend spec 配置的。例如[tools] cargo:some-crate 1.0.0 github:owner/repo 1.0.0raw 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_toolsmise 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考