如何使用 FNM 自动切换不同项目的 Node.js 版本

前言

在前端开发中，你可能经常遇到这样的窘境：

• 项目 A 比较老，必须用 Node 14 才能运行。
• 项目 B 是新项目，要求用 Node 18 以上。
• 每次切换项目，都要手动输入命令切版本，一旦忘了切换就会报一堆错。

今天，我们就来彻底解决这个问题！本文将手把手带你安装和配置目前业界最快、最流行的 Node 版本管理器 —— FNM (Fast Node Manager)。

配置完成后，只要你在终端 cd 进入某个项目，Node 版本就会自动切换，实现完全无感开发。

什么是 FNM？

FNM 是基于 Rust 语言开发的一个 Node.js 版本管理器。它的特点就是极快，比老牌的 nvm 快上百倍。而且它原生支持进入目录自动切换 Node 版本。

第一步：安装 FNM（以 Windows 为例）

1. 鼠标右键点击 Windows 开始菜单，选择 终端（管理员） 或 PowerShell（管理员）。
2. 输入以下命令并回车（利用 Windows 自带的包管理器安装）：

winget install Schniz.fnm

1. 安装完成后，关闭当前终端，重新打开一个。
2. 输入以下命令验证是否安装成功：

fnm --version

如果输出了版本号（如 fnm 1.35.x），说明安装成功！

第二步：配置“自动切换”功能（核心步骤）

为了让 FNM 能够在你进入项目目录时自动切换 Node 版本，我们需要让它和你的终端深度绑定。

1. 允许系统运行脚本（Windows 必须）

以管理员身份打开 PowerShell，运行以下命令（防止后续报错）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

(系统会询问是否确认，输入 Y 回车即可)

2. 配置终端启动脚本

在 PowerShell 中运行以下命令，打开终端的配置文件：

notepad $PROFILE

（如果系统提示“找不到文件，是否创建”，选择“是”即可）

在打开的记事本中，在最末尾粘贴以下这行代码：

fnm env --use-on-cd | Out-String | Invoke-Expression

保存并关闭记事本。

3. 生效配置

重启你的终端（或者 VS Code 的内置终端），现在自动切换功能已经配置完毕了！

第三步：在项目里创建版本配置文件

如何让 FNM 知道你的项目需要什么版本的 Node？我们只需要在项目根目录下放一个声明文件。

FNM 非常聪明，它支持两种配置文件：.node-version 和 .nvmrc。你只需要在项目里创建其中任意一个即可。

1. 我该选哪个文件？

2. 怎么配置版本号？（文件内容怎么写）

在这两个文件里，版本号的写法有以下几种，FNM 都能完美识别：

写法 A：精确版本号（最推荐、最安全）

直接锁定具体版本，保证全团队环境绝对一致。

• .node-version 内容：

  18.16.0

• .nvmrc 内容（通常习惯带个 v，不带也可以）：

  v18.16.0

写法 B：只写大版本号（自动匹配最新）

如果你只要求大版本一致，可以只写数字。FNM 会自动在本地寻找或下载该大版本下的最新小版本。

• 文件内容：

  20

  (相当于告诉 FNM：只要是 Node 20 就可以)

写法 C：使用别名（仅限 .nvmrc）

支持使用 Node.js 官方的代号（如 lts/* 代表最新的长期支持版）。

• .nvmrc 内容：

  lts/iron

⚠️ 新手避坑指南：

• 文件内容必须非常干净，不能写注释，不能写多余的空格，只写版本号。
• 不要在 Windows 下直接右键新建 .txt 重命名，容易产生隐藏后缀（如 .node-version.txt）导致 FNM 无法识别。

正确创建文件的方法：
在 VS Code 里直接新建文件。或者在项目目录下打开 PowerShell 运行这行命令来创建（它能保证编码格式绝对正确）：

# 创建 .node-version 并写入 18.16.0
Set-Content -Path .node-version -Value "18.16.0" -Encoding utf8NoBOM

第四步：见证奇迹的时刻

现在，在终端中，通过 cd 命令进入你刚刚创建了配置文件的项目目录：

cd C:\path\to\your\my-project

你会看到终端立刻弹出一行提示：

Using Node v18.16.0

如果这个版本你之前没有安装过，FNM 会非常贴心地询问你：
Can't find an installed Node.js version matching v18.16.0. Do you want to install it? (未找到该版本，是否需要安装？)

你只需要输入 y 并回车，FNM 就会自动下载并帮你切好，以后再进入这个目录就完全无感了！

附录 1：FNM 常用命令速查表

虽然配置了自动切换，但日常开发中一些手动命令也很有用：

附录 2：如何顺便把 pnpm/yarn 的版本也管起来？

FNM 只管 Node 版本。如果你想让项目连包管理器（如 pnpm）的版本也跟着自动锁定，可以使用node原生的 corepack 能力，具体可以看这篇文章：《如何使用 Node.js Corepack 自动锁定和切换项目包管理器版本》

现在，不仅 Node 版本会自动切换，当你在这个项目下运行 pnpm install 时，系统也会自动下载并使用 8.15.4 版本的 pnpm，真正实现“项目配置一人搞定，全队多电脑完美同步”！