配置下面这行后,fnm 会在切换目录时尝试选择项目需要的 Node.js 版本:

eval "$(fnm env --use-on-cd --shell zsh)"

当前 fnm 会从以下信息解析版本:

  1. 项目中的 .node-version.nvmrc
  2. 没有上述文件时,package.json 中的 engines.node
  3. 新 shell 没有项目约束时,使用 fnm default 设置的版本。

从 fnm 1.38 开始,engines.node 解析默认启用,可以通过 --resolve-engines=false 关闭。同一目录不要同时提交 .node-version.nvmrc:fnm 支持两者,但官方文档没有承诺两者同时存在时的优先顺序。

需要注意:从一个指定 Node.js 20 的项目进入完全没有版本声明的目录时,--use-on-cd 在部分版本和策略下不会主动切回 default,也可能继续保留 Node.js 20。因此,“没有版本文件就一定使用默认版本”并不可靠;应以 fnm currentnode --version 的实际输出为准。

可以随时检查:

fnm default
fnm current
node --version

推荐显式声明

对需要稳定构建的项目,最好提交一个版本文件:

# .node-version
24

.nvmrc 也可以继续使用,fnm 原生兼容它。精确到大版本通常比锁死每个补丁版本更易维护;如果运行环境要求完全一致,再写完整版本。

Monorepo 如果希望子目录继承仓库根目录的版本文件,可以配置递归查找:

eval "$(fnm env --use-on-cd --version-file-strategy recursive --shell zsh)"

参考:fnm Configurationfnm Commands