为什么终端里找不到命令？——一次 CLI 排障记

现象：同一个环境，三个工具两种命运

装完 Tavily CLI 后兴冲冲地敲下第一条搜索命令，得到的是一句最熟悉的报错：

$ tvly --version
bash: tvly: command not found

诡异的地方在于”时好时坏”：手动补一句 export PATH="$HOME/.local/bin:$PATH" 就能用，可换个新会话又打回原形。更让人困惑的是，同一天在同一台机器上装的另外两个 CLI 却毫无问题：

$ gh --version     # gh version 2.92.0        ✅
$ ctx7 --version   # 0.5.8                    ✅

三个工具，两种命运。问题出在哪？

排查：先对比，再定位

第一步：对比两种 shell 看到的世界

遇到”有时找得到、有时找不到”，第一反应应该是怀疑 调用方的环境不一致。把两种 shell 的 PATH 摆在一起：

$ bash -c 'echo $PATH'    # 普通（非登录）shell
/home/ubuntu/.nvm/versions/node/v22.16.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

$ bash -lc 'echo $PATH'   # 登录 shell
/home/ubuntu/.local/bin:/usr/local/java/jdk1.8.0_202/bin:/home/ubuntu/.nvm/versions/node/v22.16.0/bin:...:/snap/bin

关键差异一目了然：登录 shell 的 PATH 里多出了 /home/ubuntu/.local/bin——正是 tvly 所在的目录。

第二步：找到注入点

顺着这条线索去翻启动文件，很快找到两个”嫌疑人”：

# ~/.profile 第 25 行（Ubuntu 默认配置）
if [ -d "$HOME/.local/bin" ] ; then
    PATH="$HOME/.local/bin:$PATH"
fi

# ~/.bashrc 第 118 行
export PATH="$HOME/.local/bin:$PATH"

也就是说，~/.local/bin 从来不是 PATH 的”天生成员”，它依赖这两个文件在被读取的那一刻被手工塞进去。那么剩下的问题只有一个：什么样的 shell 会读它们？

第三步：排障路上自己踩的一个坑

这里必须坦白一个乌龙。排查途中我用下面这条命令验证”PATH 里到底有没有这个目录”：

$ echo $PATH | grep -c '.local/bin'
1

返回 1！看起来 PATH 里明明有，跟前面的结论矛盾了。折腾半天才意识到：正则里的 . 是任意字符通配符，所以 /usr/**local/bin** 同样命中 .local/bin 这个模式——我数到的其实是系统目录。检测字面量请务必 grep -F '.local/bin' 或写成 '\.local/bin'。

原理：你的命令由谁负责”可见”

shell 启动文件读取矩阵

bash 根据启动方式决定读哪些配置文件，这就是一切问题的根源：

shell 类型	典型场景	读 `~/.profile`？	读 `~/.bashrc`？	`~/.local/bin` 在 PATH？
登录 shell	ssh 登录、`bash -l`	✅	通常间接读	✅
交互式非登录	本地终端开新标签页	❌	✅	✅
非交互执行	脚本、CI、cron、`bash -c`、AI Agent 工具	❌	❌	❌

注意最后一行：现代自动化环境（CI 流水线、定时任务、AI Agent 的命令执行器）每条命令都是一个全新的非登录、非交互 shell——两个启动文件都不会被执行，任何依赖它们注入的 PATH 配置在那里统统不存在。

所以这不是”时好时坏”的玄学：你手动开终端时有（交互式），脚本和 Agent 调用时没有（非交互），是确定性事件。

三种安装方式，三种命运

再回头看三个工具的差异，答案已经写在它们的安装落点上：

工具	安装方式	实际落点	非登录 shell 可见？
`gh`	系统级安装	`/usr/local/bin/gh`	✅ 该目录永远在默认 PATH
`ctx7`	npm 全局（nvm）	`~/.nvm/versions/node/v22.16.0/bin/`	✅ 运行环境的父进程本身就用这个 node，bin 目录天然继承在 PATH 里
`tvly`	pip 安装	`~/.local/bin/tvly`	❌ 只有前两类 shell 能看到

现象差异 = 安装落点差异，就这么简单。

修复：三种方案与取舍

方案一：软链到系统目录（本次采用）

sudo ln -sfn ~/.local/bin/tvly /usr/local/bin/tvly

一次操作，对所有 shell、所有调用方立即生效，无需碰任何配置文件。缺点是如果将来升级导致二进制路径变化，链接要重新指向。

方案二：每次显式 export PATH

零侵入，但要在每个入口重复一遍，忘一次就翻车一次，不适合长期方案。

方案三：改 ~/.bashrc

很多人第一反应是这个，但它只对交互式 shell 有效——脚本、CI、Agent 环境根本不读它，等于没修。

我的经验法则：给”这台机器上所有进程”用的工具，放进 /usr/local/bin 这类系统目录；rc 文件只留给给人用的别名和函数。

小结

下次再遇到 command not found，按这三问走一遍，基本都能两分钟内定位：

装哪了？ ls ~/.local/bin/<cmd> 或 find 全盘搜，先确认二进制存在；
谁管 PATH？ 对照启动文件读取矩阵，确认当前 shell 类型会读哪个文件；
谁在调用？ 人开终端、脚本、CI、Agent——环境一个比一个”裸”，越自动化的调用方，越不能指望任何登录初始化。

最后再记一笔这次的小教训：grep 的模式里出现 . 时想清楚它是正则通配符还是字面量——它能帮你匹配，也能悄悄把你带进沟里。