让命令能在另一台电脑上运行

一个资料转换工具在自己的终端里能运行，换到另一台电脑却提示找不到命令；改成绝对路径后，又读不到配置。这两个故障属于不同层：Shell 要先找到可执行程序，程序再根据工作目录寻找文件。把它们都归结为“环境没装好”，会让排查越改越乱。

本课以一个读取资料清单、生成预览的教学工具为例。目标是说明一次命令运行需要哪些输入，再给另一位开发者一份能逐项验证的运行说明。示例里的路径是合成数据，不会读取或修改电脑上的文件。

命令名怎样变成可执行程序

Shell 会先解析命令行，处理引号、变量展开等语法，再决定执行什么。命令可能是别名、函数、内置命令，也可能是文件系统上的可执行程序。对于需要搜索的外部命令，PATH 给出一组按顺序查找的目录。把一个目录加进 PATH，不等于把它设成工作目录，也不会让其中的程序自动获得依赖。

同名工具可以同时存在于项目目录和系统目录。谁先被找到取决于 Shell 的解析规则、PATH 顺序，有些 Shell 还会缓存命令位置。排查时记录实际解析结果和程序版本，别只记录输入的短命令名。Bash 可以用 type -a tool 查看解析候选；其他 Shell 的语法应查其文档。

相对路径从当前工作目录解释。./bin/tool 指向当前目录下面的文件，/project/bin/tool 则是教学例中的绝对路径。绝对路径让定位明确，但换电脑后这个目录可能不存在，因此可复现说明通常约定项目根目录，再使用项目内部的相对路径。

工作目录、引号和环境要分别检查

工具从项目根运行与从上一级运行，可能拿到相同的程序，却读到不同的配置文件。运行说明应写出起始目录、配置参数、输入路径和输出位置。路径带空格时，需要按指定 Shell 的规则引用；Bash 的单引号通常保留字面文本，双引号仍允许部分展开。不要把 Bash 脚本直接当成 PowerShell 脚本运行。

进程启动时接收环境变量。Shell 中普通变量与导出给子进程的变量有区别；在子进程里修改环境，也不会反向改动父进程。编辑器启动的终端、桌面图标启动的程序和登录终端，可能使用不同的启动配置。遇到“终端能跑、编辑器不能跑”，先比较实际进程环境和启动参数。

对预览工具可以约定 READER_CONFIG 指向配置，READER_PORT 表示监听端口。使用项目专用名称，避免误改 HOME 等系统变量。缺少必需变量时应明确退出，不能悄悄选择生产配置。诊断只打印是否存在、非敏感路径和版本；令牌、密码及完整环境转储不属于普通日志。

localhost 和端口属于哪个环境

localhost 通常指当前网络环境的回环地址。浏览器运行在宿主机，工具运行在容器时，两者口中的 localhost 可能指向不同的地方。即使端口号相同，也不代表两边访问的是同一进程。先画清楚客户端、容器、宿主机和代理的位置，再查端口映射。

监听 127.0.0.1 一般只接收相应回环接口的连接，监听 0.0.0.0 表示绑定所有 IPv4 接口；实际可达性还取决于防火墙、容器映射和网络。0.0.0.0 是监听通配地址，客户端应使用能到达服务器的具体地址。向外开放预览服务前，还要检查服务是否包含私有内容与身份验证。

“端口占用”说明某次绑定失败，可能是旧预览进程，也可能是其他服务。先查看监听者的进程和启动来源，确认归属后再选择停掉自己启动的进程或换端口。随机结束进程会破坏别人的任务，也不能修正应用监听地址写错的问题。

用离线模型观察 PATH 顺序

下面的集合表示假想文件系统里存在的两个可执行文件。函数从目录列表依次找候选；缺失的目录项不会阻止后续查找。这只模拟外部程序搜索的一部分，未实现别名、内置命令、权限检查、缓存和真正执行。

executables = {"/project/bin/tool", "/usr/bin/tool"}
def resolve(name, paths):
    for directory in paths:
        candidate = directory + "/" + name
        if candidate in executables:
            return candidate
    return None
assert resolve("tool", ["/project/bin", "/usr/bin"]) == "/project/bin/tool"
assert resolve("tool", ["/usr/bin", "/project/bin"]) == "/usr/bin/tool"
assert resolve("missing", ["/usr/bin"]) is None
print(resolve("tool", ["/project/bin", "/usr/bin"]))

输出为 /project/bin/tool。前两个断言把目录顺序倒过来，命中结果也随之改变；第三个断言证明未知命令返回 None。它不能证明真实电脑上的 tool 存在，实际验证仍要检查文件可执行权限和运行时。

如果项目工具的目录根本没放进搜索列表，函数不会找到它。反过来，路径解析成功也不能证明动态库、解释器、配置和输入数据齐全。每完成一层检查，都要保留明确结果，再进入下一层。

写出能复现的运行步骤

在一次性工作目录中准备项目，先确认操作系统、指定 Shell 和运行时版本，再核对依赖锁文件。随后进入约定的项目根，设置最少的非敏感变量，用一份合成清单运行工具。每步记录实际命令、退出状态及预期文件或响应，不把“没有红字”当作成功标准。

脚本应声明解释器，明确失败时如何退出。Bash 中不能假设所有流水线失败都会成为最后的退出状态；要按脚本需求选择错误检查和流水线策略。把多个步骤连成一长串会掩盖失败位置，初次验证更适合逐步执行。

预览进程启动后，分别验证监听地址、客户端请求和内容正确性。成功启动只证明程序进入运行状态；成功返回 HTTP 也不一定证明读取的是正确输入。保存运行说明时，使用变量占位表达本机路径，避免把真实账号和凭证带入仓库。

练习：制造三个不同的故障

给教学工具编写运行清单，包含起始目录、运行时、配置路径、监听地址、端口和成功输出。分别制造 PATH 不含工具目录、从错误目录启动、端口已有监听者三种情况。每次只改变一个条件，写出观察、判断和修复步骤。

验收时，另一位读者应能指出失败发生在命令解析、文件定位还是网络绑定阶段，并在修复后得到相同的合成预览内容。再测试路径含空格和缺失必需变量：前者按指定 Shell 正确传参，后者返回明确错误且不启动服务。记录这些结果，比一句“换机器也能跑”更容易复核。