Mac终端zsh报command not found错误的排查与解决方法

这个报错的根本原因是zsh运行环境里存在错误的自定义配置：执行特定命令时，shell会把孤立的-X字符串当作独立命令尝试运行，系统里没有名为-X的可执行程序，就会抛出command not found错误。
只有cd等部分命令触发、ls正常运行，是因为错误配置只绑定了这部分命令，没有关联到ls等正常运行的命令。常见错误场景：

• 给cd等命令写别名（alias）、自定义包装函数时语法错误，把本属于其他命令的-X参数拆成了独立执行行。比如本来想实现切目录后自动列文件，写函数时换行错误：

  # 错误示例：-X被拆成独立行，每次执行cd都会触发报错
  function cd() {
    builtin cd "$@"
    ls
  }
  -X
  

• 配置终端标题、目录切换自动触发逻辑（比如切目录自动展示git分支、自动执行ls）的precmd/preexec钩子函数时，漏写了-X参数前面的命令（比如echo、printf、ls等）
• 安装第三方zsh主题、插件时，配置文件存在换行错误、参数遗漏

• 确认cd是否被自定义配置覆盖
  执行以下命令查看cd的当前定义：

  type cd
  

  如果输出显示cd是别名或者自定义shell函数，直接看输出的定义内容，就能快速定位是否存在孤立的-X片段。
  可以先执行内置cd命令绕过所有自定义配置做验证：

  builtin cd ~
  

  如果执行这条命令不报错，就能100%确认问题出在自定义别名、函数或者钩子配置上。
• 定位配置文件中的错误行
  直接搜索zsh启动加载的所有配置文件里的-X关键字：

  grep -n -- '-X' ~/.zshenv ~/.zshrc ~/.zprofile ~/.zlogin
  

  命令输出会直接标出-X所在的文件和行号，查看对应行上下文即可定位错误：
  • 如果-X是某条命令的参数，补上它前面缺失的命令名即可
  • 如果-X是无意义的冗余输入，直接删除对应行
  • 如果-X属于第三方插件/主题的配置片段，检查插件安装配置是否正确，修正换行、参数遗漏问题
• 小概率异常修复
  如果以上步骤没找到问题，执行以下命令清空zsh的命令哈希表、清除当前会话的临时别名：

  hash -r
  unalias -a
  

  再测试cd命令是否恢复正常，如果正常说明是临时会话中的错误别名、哈希缓存导致的。
• 配置生效
  配置修复完成后，执行source ~/.zshrc重载配置，或者直接重启终端，报错就会完全消失。

内容的提问来源于stack exchange，提问作者rjbcg81