FAQ-10：命令找不到（command not found）

预计阅读时间：21 分钟

问题速查表

当你在终端输入一条命令，却看到 bash: xxx: command not found 的提示时，这意味着 shell 在当前环境变量 $PATH 指定的所有目录中都没有找到名为 xxx 的可执行文件。这个错误看似简单，但背后的原因多种多样，是 Linux 新手和有经验的用户都会频繁遇到的问题。

PATH 环境变量是 Linux 命令执行的核心机制。当你输入一个命令时，shell 会按照 PATH 中列出的目录顺序逐一查找。如果所有目录都搜索完毕仍未找到匹配的可执行文件，就会抛出 command not found 错误。理解这个机制是解决所有相关问题的基础。

在实际使用中，这个错误可能出现在各种场景：刚安装完系统某些工具不可用、从 Windows 迁移到 Linux 后习惯性输入错误的命令名、使用 pip 或 npm 安装的工具无法直接调用、自定义脚本执行失败等。下面详细分析每种情况的原因和解决方案。

原因分析

PATH 环境变量未正确设置是最根本的原因。Linux 系统的命令查找依赖于 PATH 变量，它是一个由冒号分隔的目录列表。Shell 会从左到右依次搜索这些目录，直到找到匹配的可执行文件。如果命令所在的目录不在 PATH 中，shell 就无法找到它。

软件包未安装是另一个常见原因。许多 Linux 发行版采用最小化安装策略，不会预装所有工具。例如，Ubuntu 默认不安装 net-tools（包含 ifconfig、netstat）、vim、tree 等常用工具。当你需要使用这些命令时，必须先通过包管理器安装对应的软件包。

命令名称拼写错误也不容忽视。Linux 命令严格区分大小写，ping、Ping、PING 是三个完全不同的东西。此外，从 Windows 环境迁移过来的用户可能会输入 dir、cls、ipconfig 等 Windows 命令，这些在 Linux 中并不存在。

可执行文件权限问题也会导致类似错误。即使文件存在于 PATH 目录中，如果没有可执行权限（x），shell 也不会将其作为命令执行。不过这种情况通常报错信息会略有不同（如 Permission denied）。

Shell 缓存问题在某些情况下也会触发此错误。Bash 会缓存 PATH 中找到的命令路径，使用 hash 命令管理。如果之前执行过某个命令但后来被删除或移动了位置，缓存中仍然保留旧路径，再次执行时就会报 command not found。

排查决策树

遇到 command not found 时，先不要急着安装软件包，按下面的决策树逐层判断，可以少走弯路：

bash: xxx: command not found
│
├─ ① 先确认命令是否真实存在
│    ├─ which xxx / type xxx / command -v xxx
│    │    ├─ 能找到路径 → 该目录是否在 $PATH 中？
│    │    │    ├─ 在 → 检查文件权限（ls -l 看有无 x 位）
│    │    │    └─ 不在 → 加入 PATH 或创建符号链接
│    │    └─ 找不到 → 进入 ②
│    └─ 是否只是拼写错误（大小写、Windows 命令名、多余空格）
│
├─ ② 命令是否属于某个软件包
│    ├─ dpkg -l / rpm -qa 查询包是否存在
│    │    ├─ 未安装 → apt install / yum install 对应包
│    │    └─ 已安装但 which 仍找不到 → 包内命令路径未加入 PATH
│    └─ apt-file search 定位命令所属的包
│
└─ ③ 检查 shell 会话相关因素
     ├─ 刚安装的工具是否未重新登录（source ~/.bashrc）
     ├─ shell 是否缓存了旧路径（hash -r 刷新缓存）
     └─ 是否在 cron/systemd 等非交互环境（PATH 极简，需写全路径）

排查步骤

第一步：确认命令是否存在

使用 which 或 type 命令来确认目标命令是否在系统中存在，以及位于哪个目录。

# which 命令：在 PATH 中查找可执行文件
which python3
# 输出示例：/usr/bin/python3

# type 命令：显示命令类型（别名、内建命令、外部命令）
type ls
# 输出示例：ls 是 'ls --color=auto' 的别名

# command -v：更 POSIX 兼容的写法
command -v git

第二步：检查 PATH 环境变量

查看当前 PATH 的内容，确认命令所在的目录是否包含在内。

# 查看完整 PATH
echo $PATH

# 按格式输出（每个目录一行）
echo $PATH | tr ':' '\n'

# 临时修改 PATH 进行测试
export PATH="$PATH:/usr/local/bin"
your-command

第三步：确认软件包是否已安装

使用包管理器确认命令对应的软件包是否已经安装。

# Debian/Ubuntu
dpkg -l | grep 包名
apt list --installed 2>/dev/null | grep 包名

# CentOS/RHEL
rpm -qa | grep 包名

# 通用方法：用 apt-file 搜索命令属于哪个包
sudo apt install apt-file
apt-file update
apt-file search /bin/命令名

第四步：检查文件权限

确认目标文件是否具有可执行权限。

# 查看文件详细信息
ls -la /usr/bin/命令名
# 确认是否有 x（可执行）权限

# 如果没有可执行权限，添加之
chmod +x /path/to/command

第五步：刷新 Shell 缓存

清除 Bash 的命令缓存，使其重新从 PATH 中查找。

# 清除所有缓存
hash -r

# 查看当前缓存
hash

# 仅清除特定命令的缓存
hash -d 命令名

第六步：确认 Shell 类型

# 查看当前使用的 Shell
echo $SHELL
echo $0

# 不同 Shell 的配置文件不同
# bash: ~/.bashrc, ~/.bash_profile
# zsh:  ~/.zshrc
# fish: ~/.config/fish/config.fish

解决方案

安装缺失的软件包

在 Ubuntu/Debian 系统上，使用 apt 安装所需工具：

# 搜索命令属于哪个包
apt search 命令名

# 安装常用缺失工具
sudo apt install net-tools      # ifconfig, netstat, route（已废弃，建议使用 iproute2）
sudo apt install iproute2       # ip, ss（现代替代工具，通常已预装）
sudo apt install lsof           # lsof
sudo apt install jq             # jq（JSON 处理）
sudo apt install tree           # tree（目录树）
sudo apt install curl           # curl
sudo apt install wget           # wget
sudo apt install vim            # vim 编辑器
sudo apt install git            # git 版本控制
sudo apt install build-essential # gcc, g++, make

永久添加目录到 PATH

对于手动安装的工具或自定义脚本，需要将其所在目录永久添加到 PATH。

# 编辑 ~/.bashrc 或 ~/.zshrc
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
echo 'export PATH="$PATH:/opt/mytools/bin"' >> ~/.bashrc
source ~/.bashrc

# 或者创建符号链接到 PATH 中的目录
sudo ln -s /opt/mytools/bin/mytool /usr/local/bin/mytool

使用当前目录下的脚本

执行当前目录下的脚本需要用 ./ 前缀，明确告诉 shell 在当前目录查找。

# 错误：shell 在 PATH 中找不到 myscript
myscript

# 正确：在当前目录查找
chmod +x myscript
./myscript

# 或者用完整路径执行
/full/path/to/myscript

处理 pip/npm/pipx 安装的工具

Python 和 Node.js 包管理器安装的命令可能不在标准 PATH 中。

# pip 安装的工具通常在 ~/.local/bin
# 确保该目录在 PATH 中
export PATH="$PATH:$HOME/.local/bin"

# pipx 安装的工具（推荐）
pipx install package-name
pipx ensurepath

# npm 全局安装的工具
npm config get prefix
# 将输出路径下的 bin 目录加入 PATH

真实案例

案例 A：cron 任务中 PATH 被覆盖导致 rsync 报 command not found

现象：某服务器的备份脚本每天早上通过 cron 执行，最近连续多天没产生备份文件，管理员在 cron 邮件中看到如下报错：

Subject: Cron <root@backup01> /opt/scripts/backup.sh
Body:
/opt/scripts/backup.sh: line 12: rsync: command not found
/opt/scripts/backup.sh: line 18: tar: command not found

排查过程：在交互终端中 which rsync 正常输出 /usr/bin/rsync，tar 也能用，说明命令本身存在。查看脚本开头发现：

#!/bin/bash
export PATH="/opt/custom/bin"    # 错误：直接覆盖了系统 PATH
...
rsync -avz /data /backup/        # 第 12 行

根因：脚本第一行用 export PATH=... 覆盖（而非追加）了系统 PATH，后续调用 rsync、tar 时 shell 只在 /opt/custom/bin 里查找，自然全部 command not found。交互终端不受影响是因为执行的是另一份干净的环境。cron 环境的 PATH 本来就比交互 shell 精简（通常只有 /usr/bin:/bin），再被覆盖就雪上加霜。

修复：把覆盖改为追加，并在脚本开头显式声明完整 PATH：

#!/bin/bash
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/custom/bin"
# 或最保守的做法：关键命令写绝对路径
rsync_cmd="/usr/bin/rsync"

验证：手动执行 bash /opt/scripts/backup.sh 无报错；第二天 cron 邮件显示备份完成。建议在所有脚本开头加 echo "PATH=$PATH" >&2 便于将来快速定位类似问题。

案例 B：pip 安装的工具找不到（~/.local/bin 未加入 PATH）

现象：用户执行 pip install --user httpie 安装 HTTP 命令行工具，安装成功后直接运行却报错：

$ http https://example.org
bash: http: command not found

排查过程：

$ which http
which: no http in (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin)
$ ls -l ~/.local/bin/http
-rwxr-xr-x 1 user user 12345 Jul 10 14:22 /home/user/.local/bin/http
$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

根因：文件已成功安装且具有执行权限，但 ~/.local/bin 根本不在 PATH 中（Ubuntu 22.04 之前的版本不会自动加入该目录）。pip 的安装目录与 shell 的查找目录脱节。

修复：把 ~/.local/bin 永久加入 PATH：

$ echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
$ source ~/.bashrc
$ http https://example.org     # 验证成功

验证：which http 现在输出 /home/user/.local/bin/http，命令可正常使用。若使用 pipx 安装工具，直接执行 pipx ensurepath 可自动完成同样的 PATH 配置。

案例 C：Shell 缓存导致删除的旧命令仍然被执行

现象：用户卸载了旧版 Python 并安装了新版，但执行 python 仍然指向旧版路径。

$ which python
/usr/local/bin/python        # 旧版路径
$ /usr/local/bin/python --version
Python 2.7.18                # 已卸载的旧版

$ ls /usr/local/bin/python
ls: cannot access '/usr/local/bin/python': No such file or directory
# 文件已不存在，但 which 仍然报告这个路径

根因：Bash 缓存了 python 命令的路径（/usr/local/bin/python），即使文件已删除，缓存仍然保留旧路径。

修复：hash -r 清除所有缓存，或 hash -d python 清除特定命令的缓存。之后 which python 会重新从 PATH 查找。

案例 D：sudo 环境下 PATH 被重置导致自定义命令不可用

现象：管理员在 /opt/custom/bin 中安装了自定义部署工具 deploy-tool，普通用户执行正常，但 sudo 执行时报 command not found：

$ deploy-tool --version
deploy-tool v2.1.0

$ sudo deploy-tool --version
sudo: deploy-tool: command not found

排查过程：

# 普通用户的 PATH
$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/custom/bin

# sudo 环境的 PATH（受 secure_path 影响）
$ sudo env | grep PATH
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

根因：sudo 默认使用 env_reset 策略，会重置环境变量为安全的默认值。 /etc/sudoers 中的 secure_path 定义了 sudo 可用的 PATH，自定义目录不在其中。

修复：有三种方案，按安全性从低到高排列：

# 方案一：在 sudoers 中添加自定义目录（谨慎）
sudo visudo
# 在 secure_path 行追加:/opt/custom/bin
Defaults    secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/custom/bin"

# 方案二：使用 sudo -E 保留当前环境（需要 sudoers 配置）
sudo -E deploy-tool --version
# 需要添加: Defaults env_keep += "PATH"

# 方案三：使用绝对路径（最安全）
sudo /opt/custom/bin/deploy-tool --version

预防：自定义工具优先安装到 /usr/local/bin（已在默认 secure_path 中），或使用绝对路径调用。避免在 sudoers 中过度放宽 PATH 限制。

案例 E：Docker 容器内基础命令缺失

现象：基于 alpine 镜像构建的容器内执行常用命令时报 command not found：

$ docker run --rm alpine ping google.com
ping: not found

$ docker run --rm alpine curl http://example.com
/bin/sh: curl: not found

排查过程：

# 查看容器内的可用命令
$ docker run --rm alpine ls /bin/
sh    busybox

# alpine 镜像极度精简，只包含 busybox 提供的基础命令

根因：Alpine 镜像为了追求最小体积（约 5MB），不包含完整的 GNU 工具链。它使用 BusyBox 提供精简版命令，很多常用工具（ping、curl、wget、vim 等）需要单独安装。

修复：在 Dockerfile 中安装所需工具：

# Dockerfile
FROM alpine:3.18

# 安装常用工具
RUN apk add --no-cache \
    curl \
    wget \
    ping \
    bash \
    vim \
    net-tools \
    bind-tools

# 或使用 alpine 的完整版镜像（体积更大）
# FROM alpine:3.18  # 精简版 ~5MB
# FROM alpine:3.18  # 完整版通过 apk 安装后约 30MB

预防：选择基础镜像时权衡体积与功能需求。生产环境可使用多阶段构建：构建阶段用完整镜像，运行阶段用精简镜像。在 CI 中用 docker exec 容器名 which 命令 验证关键工具可用性。

案例 F：snap 安装的命令不在传统 PATH 中

现象：Ubuntu 24.04 上用 snap 安装了 node，但 bash 中执行报 command not found：

$ snap install node --classic
$ node --version
bash: node: command not found

排查过程：

# snap 安装的命令位置
$ ls /snap/bin/
node    npm    npx

# 检查 PATH 是否包含 /snap/bin
$ echo $PATH | tr ':' '\n' | grep snap
# 无输出——/snap/bin 不在 PATH 中

根因：snap 安装的可执行文件位于 /snap/bin，该目录需要被添加到 PATH。Ubuntu 桌面版通常会自动配置，但服务器版或 SSH 登录后可能缺失。

修复：

# 添加 /snap/bin 到 PATH
echo 'export PATH="$PATH:/snap/bin"' >> ~/.bashrc
source ~/.bashrc

# 或创建符号链接到标准路径
sudo ln -s /snap/bin/node /usr/local/bin/node
sudo ln -s /snap/bin/npm /usr/local/bin/npm

预防：使用 snap 安装工具后，立即用 command -v 工具名 验证。如果 PATH 中缺少 /snap/bin，在 ~/.profile 中永久添加。

案例 G：conda 环境切换后命令丢失

现象：用户在 conda 环境中安装了 python，退出环境后命令消失，重新进入环境后仍然找不到：

$ conda activate myenv
(myenv) $ which python
/home/user/miniconda3/envs/myenv/bin/python

(myenv) $ conda deactivate
$ conda activate myenv
(myenv) $ python --version
bash: python: command not found

排查过程：

# 检查 conda 初始化是否正确
$ conda init bash
$ cat ~/.bashrc | grep conda
# 如果没有 conda 初始化代码，说明 shell 未正确配置

# 检查环境中的 python 是否存在
$ ls /home/user/miniconda3/envs/myenv/bin/python
ls: cannot access: No such file or directory

根因：conda 环境损坏或初始化不完整。可能是环境创建失败、conda base 环境更新后配置丢失、或 ~/.bashrc 中的 conda 初始化代码被误删除。

修复：

# 重新初始化 conda
conda init bash
source ~/.bashrc

# 重建损坏的环境
conda remove -n myenv --all
conda create -n myenv python=3.11
conda activate myenv

# 验证
which python

预防：不要手动修改 ~/.bashrc 中的 conda 初始化代码块。定期执行 conda update conda 保持 conda 自身更新。重要环境导出配置：conda env export > environment.yml。

预防措施

• 安装系统后首先配置好 PATH 环境变量，确保 /usr/local/bin、$HOME/.local/bin 等常用目录包含在内
• 使用 apt-file search /bin/xxx 在安装前确认命令属于哪个包，避免盲目搜索
• 为自定义脚本统一放置在固定目录（如 $HOME/.local/bin），并确保该目录在 PATH 中
• 定期使用 hash -r 清除 shell 缓存，尤其是在删除或移动了可执行文件之后
• 在 cron、systemd 等非交互环境中运行的脚本，开头显式声明完整 PATH 或对关键命令使用绝对路径，不要依赖交互环境的 PATH
• 安装新工具后立即用 command -v 工具名 验证一次，把问题消灭在配置阶段
• 常用工具目录统一在 ~/.profile 中追加一次，避免在多个配置文件里重复设置 PATH 导致互相覆盖

进阶排查技巧

使用 debugfs 跟踪命令查找过程

Bash 提供了内置的调试机制，可以跟踪命令查找过程：

# 启用命令查找调试
set -x
your-command
set +x

# 或使用 bash -x 执行脚本
bash -x your-script.sh

# 查看 shell 的命令查找历史
history | grep "command not found"

分析 /etc/shells 和默认 Shell

不同 Shell 的命令查找机制略有差异：

# 查看系统支持的 Shell
cat /etc/shells

# 查看当前用户的默认 Shell
getent passwd $(whoami) | cut -d: -f7

# 不同 Shell 的配置文件
# bash: ~/.bashrc, ~/.bash_profile, ~/.profile
# zsh: ~/.zshrc, ~/.zprofile
# fish: ~/.config/fish/config.fish

使用 strace 跟踪系统调用

当 which/type 无法定位问题时，可以用 strace 观察命令查找的底层行为：

# 跟踪命令查找的文件系统操作
strace -e openat,access your-command 2>&1 | grep -E "ENOENT|PATH"

# 跟踪 shell 的命令解析过程
strace -f -e trace=execve bash -c "your-command"

批量检查命令可用性

在部署脚本中批量验证关键命令是否存在：

# 定义需要检查的命令列表
REQUIRED_CMDS="git docker curl wget ssh rsync"

for cmd in $REQUIRED_CMDS; do
    if ! command -v "$cmd" &>/dev/null; then
        echo "[MISSING] $cmd is not installed"
    else
        echo "[OK] $cmd: $(command -v $cmd)"
    fi
done

常见误区与陷阱

• 不要盲目使用 chmod -R 777：这不会解决 command not found 问题，反而引入安全隐患
• 不要在多个配置文件中重复设置 PATH：容易导致覆盖或循环引用
• 不要忽略 Shell 类型差异：bash 和 zsh 的配置文件不同，切换 Shell 后需要检查对应配置
• 不要在生产环境使用 source ~/.bashrc 修复问题：这只是临时方案，需要找到根因并永久修复
• 不要忽略非交互环境的 PATH 差异：cron、systemd、SSH 远程执行的 PATH 通常比交互 shell 精简

故障复现与验证清单

修复 command not found 问题后，使用以下清单验证：

# 1. 验证命令可用
command -v 命令名

# 2. 验证 PATH 正确
echo $PATH | tr ':' '\n' | grep "目标目录"

# 3. 验证文件权限
ls -la $(which 命令名)

# 4. 验证非交互环境
env -i PATH="$PATH" 命令名

# 5. 验证 cron 环境（模拟最小 PATH）
crontab -e
# 添加: * * * * * /usr/bin/env PATH=/usr/bin:/bin 命令名 >> /tmp/cron-test.log 2>&1
# 等待一分钟后检查 /tmp/cron-test.log

最佳实践

• 善用 tab 补全：输入命令前几个字符后按 Tab 键，shell 会自动补全或列出候选命令，可以有效避免拼写错误
• 使用 alias 简化长命令：在 ~/.bashrc 中定义常用别名，如 alias ll='ls -la'，减少输入错误的概率
• 优先使用绝对路径排查：遇到 command not found 时，先用 which 和 find 确认命令的实际位置，再决定是安装、链接还是修改 PATH
• 了解包管理器的文件列表功能：dpkg -L 包名 可以查看已安装包的所有文件，快速找到命令所在路径
• 区分登录 shell 和非登录 shell：~/.bashrc 和 ~/.profile 的加载时机不同，通过 SSH 或 cron 执行命令时可能加载不同的配置文件，导致 PATH 不一致

延伸阅读

附录：常用命令速查表

附录：Shell 配置文件加载顺序

# 登录 Shell（SSH、控制台登录）
# 1. /etc/profile（系统级）
# 2. ~/.bash_profile 或 ~/.bash_login 或 ~/.profile（用户级，按顺序找到第一个执行）

# 非登录 Shell（桌面终端、cron）
# 1. /etc/bash.bashrc（Debian/Ubuntu）或 /etc/bashrc（CentOS/RHEL）
# 2. ~/.bashrc

# 交互式非登录 Shell 读取 ~/.bashrc
# 非交互式 Shell（脚本、cron）读取 $BASH_ENV 指定的文件

# 验证当前 Shell 类型
echo $0
# -bash = 登录 Shell
# bash = 非登录 Shell

附录：PATH 变量调试技巧

# 按目录逐行显示 PATH
echo $PATH | tr ':' '\n' | nl

# 检查特定目录是否在 PATH 中
echo $PATH | tr ':' '\n' | grep -q "/usr/local/bin" && echo "Found" || echo "Not found"

# 追踪命令查找过程
strace -e openat,access your-command 2>&1 | grep -E "ENOENT|PATH"

# 临时添加目录到当前 Shell
export PATH="/new/dir:$PATH"

# 永久添加到配置文件
echo 'export PATH="/new/dir:$PATH"' >> ~/.bashrc
source ~/.bashrc

附录：常见发行版的 PATH 默认值

# Ubuntu/Debian（普通用户）
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

# CentOS/RHEL（普通用户）
/usr/local/bin:/usr/bin:/bin

# root 用户通常额外包含
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

# cron 环境（极简）
/usr/bin:/bin

# systemd 服务环境
通常为空或仅包含 /usr/bin:/bin

附录：Shell 变量与环境变量

# 显示所有 Shell 变量
set

# 显示所有环境变量
env
printenv

# 设置环境变量（当前 Shell）
export MY_VAR="value"

# 查看特定变量
echo $PATH
echo $HOME
echo $USER

# 删除变量
unset MY_VAR

# 变量作用域
# 普通变量：仅当前 Shell
MY_VAR="value"

# 环境变量：子进程继承
export MY_VAR="value"

# 只读变量：不可修改
readonly MY_VAR="value"

附录：常见 Shell 错误信息

案例 H：Shell alias 覆盖新安装的同名命令

现象：管理员安装了自定义的 ll 脚本到 /usr/local/bin/ll，但执行 ll 时始终调用的是 alias 而非脚本：

# 确认脚本存在
$ ls -la /usr/local/bin/ll
-rwxr-xr-x 1 root root 2048 Jul 15 10:00 /usr/local/bin/ll

# 但执行的是 alias
$ type ll
ll is aliased to 'ls -la'

# alias 优先于 PATH 查找
$ ll
total 48
drwxr-xr-x 6 user user 4096 Jul 15 ...

根因：Bash 命令查找顺序为 alias → 函数 → 内建命令 → PATH。alias 始终优先于 PATH 中的可执行文件，即使同名脚本已正确安装。

修复：使用反斜杠绕过 alias，或取消 alias 定义：

# 绕过 alias
\ll
command ll

# 取消 alias
unalias ll

预防：为自定义脚本命名时避免与系统命令或常用 alias 冲突。安装新工具后用 command -v 工具名 验证实际调用的是哪个。

案例 I：SSH 远程执行命令因非交互环境 PATH 精简而失败

现象：用户在本地终端可以正常执行 docker 命令，但通过 SSH 远程执行时报 command not found：

# 本地正常
$ docker --version
Docker version 24.0.7

# SSH 远程执行失败
$ ssh user@server "docker --version"
bash: docker: command not found

# 检查 docker 安装位置
$ which docker
/usr/bin/docker

排查过程：

# SSH 远程执行时的 PATH
$ ssh user@server 'echo $PATH'
/usr/local/bin:/usr/bin:/bin

# 本地交互 Shell 的 PATH
$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/home/user/.local/bin

# SSH 非交互执行使用精简 PATH

根因：SSH 远程执行命令时使用非交互式 Shell，加载的 PATH 通常比登录 Shell 精简。/usr/local/bin 等目录可能不在其中。

修复：

# 方案一：SSH 远程执行时显式声明 PATH
$ ssh user@server 'export PATH=$PATH:/usr/local/bin; docker --version'

# 方案二：在 ~/.ssh/environment 或 /etc/environment 中配置
# 方案三：使用完整路径执行
$ ssh user@server '/usr/bin/docker --version'

预防：部署脚本时在脚本开头显式声明完整 PATH，不要依赖 SSH 远程执行的默认环境。使用 env -i PATH=... 命令 模拟非交互环境测试。