项目特定配置 (.nvmrc)

概述

本文档涵盖了 Node 版本管理器 (NVM) 生态系统中 .nvmrc 文件的目的、格式和用法。 .nvmrc 文件允许开发人员按项目指定 Node.js 版本，从而在不同项目之间切换时实现自动版本切换。

有关手动管理 Node.js 版本的信息，请参阅基本命令。有关 LTS（长期支持）版本管理的信息，请参阅别名和 LTS 版本。

.nvmrc 的目的

该 .nvmrc 文件充当项目特定配置文件，声明项目应使用的 Node.js 版本。这实现了：

所有项目开发者之间一致的 Node.js 环境
切换目录时自动版本切换
简化新团队成员的上手流程
具有一致 Node.js 版本的可靠 CI/CD 管道执行

来源：nvm.sh508-514 nvm.sh603-628

.nvmrc 文件格式

一个 .nvmrc 文件遵循以下格式规则：

它应将其主要内容包含为单个 Node.js 版本规范。
可以使用 # 字符添加注释（# 之后的所有内容都将被忽略）。
每行都会去除空白字符。
版本可以以 NVM 支持的各种格式指定。

有效的版本规范

.nvmrc 文件中以下格式是有效的：

14.15.0     # Specific version (most common)
14          # Major version (latest of that major version)
lts/gallium # Named LTS release
lts/*       # Latest LTS version
node        # Latest released Node.js version

此外，对于高级用例，该文件可以包含用等号（=）分隔的键值对，限制是 node 不能用作键。

来源：nvm.sh534-601

图示：.nvmrc 解析过程

来源：nvm.sh489-514 nvm.sh534-601

图示：.nvmrc 与 NVM 的集成

来源：nvm.sh489-514 nvm.sh534-601 nvm.sh603-628

使用 .nvmrc 文件

创建 .nvmrc 文件

要创建 .nvmrc 文件，只需在项目根目录中创建名为 .nvmrc 的新文件，然后添加所需的 Node.js 版本。

自动版本切换

当您的项目中有 .nvmrc 文件时，您可以使用以下命令自动切换到指定的 Node.js 版本：

不带任何参数，nvm use 将会查找 .nvmrc 文件并使用其中指定的版本。

来源：nvm.sh603-628

位置解析

NVM 从当前目录开始，向上搜索父目录，直到找到 .nvmrc 文件或到达根目录。这种遍历是在 nvm_find_up 函数中实现的。

来源：nvm.sh499-506

.nvmrc 验证规则

.nvmrc 文件会通过 nvm_process_nvmrc 函数进行验证，该函数强制执行多项规则：

所有非注释内容必须是以下之一：
- 单个有效版本说明符
- 多个键值对，每对用单个等号（=）分隔。
空文件或仅包含注释的文件被视为无效。
键 node 不能在键值对中使用。

如果验证失败，NVM 将显示一条指示问题的错误消息。

来源：nvm.sh516-532

.nvmrc 在 CI/CD 环境中

.nvmrc 文件在 CI/CD 管道中特别有用，可以确保开发和部署环境之间 Node.js 版本的一致性。许多 CI 系统（如 GitHub Actions、Travis CI 和 CircleCI）会自动识别 .nvmrc 文件，并使用它们来安装指定的 Node.js 版本。

使用 .nvmrc 文件的示例 GitHub Actions 工作流

最佳实践

始终在您的项目中包含 .nvmrc 文件：这可确保所有环境的一致性。
指定确切版本：为确保完全可复现，请使用特定版本，例如 14.15.0，而不是仅使用 14。
升级 Node.js 时更新 .nvmrc：使文件与项目的实际 Node.js 版本要求保持同步。
在 README 中记录：在项目 README 中提及 .nvmrc 的使用，以指导新开发人员。
与 package.json 的 engines 字段结合使用：为了额外的安全性，还要在 package.json 中指定 Node.js 版本。

常见问题和故障排除

无效的 .nvmrc 格式

如果 NVM 报告您的 .nvmrc 文件无效，请确保：

文件包含单个 Node.js 版本规范。
没有意外的字符或换行符。
任何键值对都使用了正确的格式。

来源：nvm.sh516-532

未安装版本

如果 .nvmrc 中指定的版本未安装，NVM 将显示错误消息。您可以通过运行以下命令来安装所需版本：

不带任何参数，nvm install 将使用 .nvmrc 中的版本。

.nvmrc 未找到

如果 NVM 找不到 .nvmrc 文件，请验证：

文件名是否完全是 .nvmrc（而不是 nvmrc 或 .nvmrc.txt）。
文件是否存在于您的项目目录或任何父目录中。
文件是否具有适当的读取权限。