npm使用的环境变量及其用法

了解 npm 的环境变量能让你更自如地控制和定制 npm 的行为。下面我将为你介绍一些常用的 npm 环境变量及其用法，并提供一些使用上的建议。

🔧 npm 环境变量详解与使用指南

📋 常用 npm 环境变量概览

下表汇总了一些常用的 npm 环境变量及其典型用途：

💡 核心环境变量详解

1. npm_config_* 变量

npm 的运行行为可以通过 npm_config_ 开头的环境变量进行配置。

• 设置方式与优先级：npm 获取配置的顺序从高到低是：命令行标志 (Command Line Flags) > 环境变量 (Environment Variables) > npmrc 文件 > 默认配置。这意味着通过命令行参数设置的选项会覆盖环境变量。

• npm_config_cache：这个变量用于覆盖 npm 默认的缓存目录路径。这在离线开发（你需要指定一个预先准备好的缓存目录）或希望将缓存放到特定磁盘（如空间更大的数据盘或更快的 SSD）时非常有用。使用时通常需配合 --offline 参数：

  # 临时设置缓存目录并启用离线模式
  npm_config_cache="/opt/offline-resources/npm-cache" npm install --offline --optional=false

• npm_config_offline：将其设置为 true 会强制 npm 在离线模式下工作，仅使用本地缓存，不尝试任何网络连接。等同于在命令后添加 --offline 参数。

• 其他常用 npm_config_ 变量：

  • npm_config_registry：设置 npm 包的下载源。

  • npm_config_prefix：设置全局安装的根目录。

2. npm_package_* 变量

npm 会自动将你项目的 package.json 文件中的字段转换为以 npm_package_ 开头的环境变量2。例如，package.json 中的 name 和 version 字段可以通过 npm_package_name 和 npm_package_version 访问。这在 npm scripts 中非常有用，可以让脚本动态地获取项目信息：

{
  "scripts": {
    "echo:name": "echo $npm_package_name",
    "echo:version": "echo $npm_package_version",
    "archive:coverage": "mkdir -p coverage_archive/$npm_package_version && cp -r coverage/* coverage_archive/$npm_package_version/"
  }
}

3. NODE_PATH

这是一个由 Node.js 本身识别的环境变量，而非 npm 专属。它用于告诉 Node.js 除了当前项目的 node_modules 之外，还在哪些额外的目录中查找模块。

• 注意：从 Node.js v6 开始，NODE_PATH 被视为过时 (deprecated)，因为 Node.js 的模块解析算法已经非常完善。通常，更推荐使用项目本地的 node_modules 或通过 npm link 进行开发。但在一些遗留项目或特殊环境中可能仍会用到。

4. 其他实用变量

• npm_lifecycle_event：表示当前正在执行的 npm script 的名称（例如 install, start, test等）。这在编写复杂的脚本时，可以让你根据正在运行的生命周期事件执行不同的操作。

🔍 如何查看所有环境变量

要查看当前 npm 运行时可用的所有环境变量（这是一个很长的列表），可以在你的项目目录下运行：

npm run env

如果你只想查看与当前 package.json 内容相关的变量，可以使用：

npm run env | grep npm_package

🛠️ 如何使用环境变量

在 npm scripts 中使用

在 package.json 的 scripts 字段中，你可以直接通过 $变量名（Unix-like系统）或 %变量名%（Windows）来引用环境变量：

{
  "scripts": {
    "dev": "NODE_ENV=development node app.js",
    "test": "echo \"Testing package: $npm_package_name@$npm_package_version\"",
    "serve:coverage": "http-server coverage_archive/$npm_package_version -p $npm_package_config_port"
  },
  "config": {
    "port": 3000
  }
}

上面的例子中，npm_package_config_port 来自于 package.json 中 config 对象下的 port 字段。

在命令行中临时设置

你可以在执行命令前临时设置环境变量，这只对当前命令生效：

# Unix-like 系统 (Linux, macOS)
npm_config_cache=/tmp/cache npm install

# Windows (Command Prompt)
set npm_config_cache=C:\temp\cache && npm install

# Windows (PowerShell)
$env:npm_config_cache='C:\temp\cache'; npm install

在系统中持久化设置

如果你希望某个环境变量永久生效，可以将其添加到你的 shell 配置文件中（如 ~/.bashrc, ~/.zshrc, ~/.bash_profile）：

# 将以下内容添加到 ~/.bashrc 或类似文件末尾
export npm_config_cache=/home/yourusername/.npm-offline-cache

然后运行 source ~/.bashrc 使其立即生效，或重新打开终端窗口。

也可以在系统的环境变量设置界面（Windows）或全局配置文件（如 ~/.npmrc）中进行设置。

⚠️ 重要注意事项

1. 变量名大小写：大多数 npm_config_ 环境变量不区分大小写，但为了清晰和一致性，通常使用小写。NODE_PATH 等传统环境变量通常大写。

2. 配置优先级：记住命令行参数 > 环境变量 > npmrc 文件的优先级顺序。如果你在多个地方设置了同一个配置，优先级高的会覆盖优先级低的。

3. 离线模式需缓存完整：使用 npm_config_offline=true 或 --offline 时，务必确保所有依赖包已经存在于缓存中，否则安装会失败。

4. 缓存目录权限：如果你自定义了 npm_config_cache 目录，请确保运行 npm 的用户对该目录有读写权限。

5. NODE_PATH 的过时性：如前所述，优先使用项目本地的 node_modules，而不是依赖 NODE_PATH，除非你有非常特殊的理由。

希望这些信息能帮助你更好地理解和使用 npm 环境变量。