Zsh / Node / vfox 归档笔记

util62026/4/9大约 4 分钟

Zsh / Node / vfox 归档笔记

记录时间：2026-03-19

这份文档整理了我这次帮你排查 node command not found 时涉及的 shell 概念、zsh 加载顺序，以及 vfox / PATH 的正确放置方式，方便以后回看。

1. 这次问题的本质

你遇到的现象是：

打开新终端后，node 偶尔变成 command not found
但机器上实际上已经安装了 Node
同时你在用 vfox 管理版本和 shims

真正的问题不是 “Node 没装”，而是：

某些 shell 会话里 PATH 没有带上 Node 的实际路径
或者 vfox 的 shim 没有生效
或者 shell 初始化文件的加载顺序不对

最后我采取的兜底方案是：

在 ~/.zshenv 里加入基础 PATH
在 ~/.zprofile 里做 login shell 的初始化
在 ~/.zshrc 里放交互式配置和 vfox 的补充激活

2. shell 的两条维度

zsh 相关配置，最好从两个维度理解：

登录 shell

表示“登录时启动的 shell”。

常见于：

打开一个新的终端窗口
SSH 登录
某些 GUI 终端启动流程

适合放：

环境初始化
登录时要加载的 PATH
版本管理器的激活

交互式 shell

表示“给人直接输入命令用的 shell”。

你平时在终端里敲命令，通常就是交互式 shell。

适合放：

alias
prompt
补全
高亮
交互体验相关插件

非交互式 shell

表示“主要执行脚本，不等待你输入命令”。

例如：

zsh -c 'echo hi'
zsh script.zsh

这类 shell 应该尽量少做重初始化。

3. zsh 的加载顺序

zsh 会按照 shell 类型加载不同配置文件。

只要是 zsh，都会读

~/.zshenv

用途：

放最基础、最稳定、所有场景都需要的设置
典型是基础 PATH

注意：

这里会被所有 zsh 会话读取
所以不要放太重的逻辑

只在登录 shell 里读

~/.zprofile

用途：

登录环境初始化
适合放 Homebrew、版本管理器等 login shell 相关 PATH 设置

只在交互式 shell 里读

~/.zshrc

用途：

alias
prompt
插件
补全
交互体验配置

登录 shell 末尾阶段可读

~/.zlogin

一般不常用，通常不是首选放置位置。

4. 典型加载顺序

登录 + 交互 shell

通常顺序是：

/etc/zshenv
~/.zshenv
/etc/zprofile
~/.zprofile
/etc/zshrc
~/.zshrc
/etc/zlogin
~/.zlogin

交互但非登录 shell

通常顺序是：

/etc/zshenv
~/.zshenv
/etc/zshrc
~/.zshrc

非交互 shell

通常只有：

/etc/zshenv
~/.zshenv

5. 每个文件应该放什么

`~/.zshenv`

放：

所有 zsh 都需要的最基础 PATH
必须全局可见的环境变量

不建议放：

很重的初始化
需要交互的逻辑
很慢的外部命令

`~/.zprofile`

放：

login shell 的环境初始化
Homebrew、vfox 之类和登录环境强相关的东西

`~/.zshrc`

放：

alias
函数
prompt
补全
插件
交互式 shell 才需要的逻辑

6. 这次为什么会掉 `node`

主要有这几个原因：

~/.zshrc 里有一行写坏了
- export PATH="...:$PATH"alias claude="..."
- 这是把两条命令粘在一起了
vfox 的激活只靠部分 shell 文件
- 某些终端启动方式没走到你期望的文件
- 或者加载顺序不稳定
没有最底层兜底
- 如果新 shell 没正确执行完整的交互配置，node 就找不到
- 最后把真实 Node 路径也加进了 ~/.zshenv

7. 我们最终采用的稳妥策略

`~/.zshenv`

加入基础 PATH 兜底：

export PATH="/opt/homebrew/bin:/opt/allsdks/nodejs/current/bin:$HOME/.version-fox/shims:$PATH"

意义：

无论登录 shell、交互 shell、非交互 shell，node 都尽量可见

`~/.zprofile`

export PATH="/opt/homebrew/bin:$HOME/.version-fox/shims:$PATH"

if command -v vfox >/dev/null 2>&1; then
  eval "$(vfox activate zsh)"
fi

意义：

让登录 shell 尽早进入正确环境
在 vfox 存在时补上它的激活逻辑

`~/.zshrc`

交互配置里保留 vfox 的补充激活，但放在更靠后的位置：

export PATH="$HOME/.version-fox/shims:$PATH"

if command -v vfox >/dev/null 2>&1; then
  eval "$(vfox activate zsh)"
fi

意义：

交互式 shell 也保持一致
后续别的 PATH 修改不容易把 vfox 挤掉

8. 排查时常用命令

看当前 shell 类型

echo $0
echo $SHELL
echo $ZDOTDIR

看 PATH 和命令解析

echo $PATH
command -v node
command -v vfox
node -v

检查配置语法

zsh -n ~/.zshenv
zsh -n ~/.zprofile
zsh -n ~/.zshrc

zsh -l

exec zsh -l

9. 以后遇到类似问题的判断顺序

先确认 node 到底是“命令没找到”，还是“进程跑崩了”
再看 command -v node 和 echo $PATH
再确认 shell 类型：
- login shell
- interactive shell
- non-interactive shell
再看 ~/.zshenv、~/.zprofile、~/.zshrc 的职责是否正确
最后才检查 vfox 自己是否异常

10. 当前结论

当前这台机器上：

vfox 是正常的
Node 真实路径是可用的
node 已经通过 ~/.zshenv 做了兜底
以后如果再次出现 command not found: node，优先怀疑：
- 终端没完全刷新
- 启动了特殊 shell
- ZDOTDIR 被改了