怎么在npm scripts中跨平台设置Node.js环境变量

为什么直接在 npm scripts 中写环境变量会报错？

许多开发者在编写前端或 Node.js 构建脚本时，习惯于按照 POSIX 标准在终端输入如下指令：

"scripts": {
  "build": "NODE_ENV=production node build.js"
}

在 macOS 或各类 Linux 服务器（如 Ubuntu、CentOS）上运行 npm run build 时，这段脚本能够完美工作。Bash 或 Zsh 能够准确识别 KEY=value 格式，将其作为当前子进程的临时环境变量传入，并在执行完毕后自动销毁，既高效又不污染全局环境。

然而，一旦团队成员在 Windows 环境下克隆项目并执行相同的 npm run build，终端就会立即弹出如下经典错误：

'NODE_ENV' 不是内部或外部命令，也不是可运行的程序或批处理文件。

这是因为 npm 在 Windows 系统中默认唤起的是 cmd.exe 解释器。在 Windows CMD 的命令语法中，并不存在直接在命令前定义临时变量的语法规则；CMD 将 NODE_ENV=production 的整体视作一个可执行程序的名称去寻找，自然无法找到该命令。

有些开发者尝试将其修改为 Windows CMD 所支持的 set 语法：

"scripts": {
  "build": "set NODE_ENV=production && node build.js"
}

这种写法不仅在 macOS / Linux 上无法执行，而且在 Windows CMD 中隐藏着一个极为隐蔽的“尾随空格陷阱”：在 CMD 中，set NODE_ENV=production && 中间若在 production 和 && 之间留有空格，CMD 会将空格视为变量值的一部分。代码中通过 process.env.NODE_ENV 读到的字符串实际上是 "production "（末尾带有一个空格），这会导致所有 if (process.env.NODE_ENV === 'production') 的严格相等判断全部失效。

标准解决方案：使用 cross-env 规范配置

为了彻底抹平各大操作系统之间的 Shell 命令解析差异，社区诞生了 cross-env。它是目前 Node.js 生态中使用最为广泛、稳定性经过长期验证的跨平台环境变量解决方案。

cross-env 的底层工作机制

cross-env 的核心思路非常清晰：它自身是一个基于 Node.js 编写的 CLI 命令行工具。当你在 npm scripts 中以 cross-env 作为命令前缀时，npm 会首先执行位于 node_modules/.bin 下的 cross-env 脚本。

cross-env 启动后，会在内部解析紧随其后的所有参数，自动分离出所有的 KEY=VALUE 键值对与后续的真实可执行命令。随后，它通过内置的 cross-spawn 库，调用 Node.js 的子进程模块（child_process.spawn），将提取到的环境变量对象安全地注入到子进程的运行上下文中。

完整实操四步法

在实际项目中使用 cross-env 只需要完成以下标准步骤：

第 1 步：安装 cross-env 依赖

因为 npm scripts 通常用于本地开发、测试以及生产镜像构建阶段，因此将 cross-env 安装在开发依赖（devDependencies）中即可：

# 使用 npm
npm install --save-dev cross-env

# 使用 pnpm
pnpm add -D cross-env

# 使用 yarn
yarn add -D cross-env

第 2 步：修改 package.json 中的 scripts 配置

在需要设定环境变量的命令最前方加上 cross-env，紧接着声明键值对，最后写要执行的目标命令：

{
  "name": "my-cross-platform-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "cross-env NODE_ENV=development PORT=3000 node server.js",
    "build": "cross-env NODE_ENV=production API_BASE=https://api.example.com node build.js",
    "test": "cross-env NODE_ENV=test CI=true mocha"
  },
  "devDependencies": {
    "cross-env": "^7.0.3"
  }
}

如果需要同时注入多个环境变量，只需用半角空格隔开即可，无需添加任何 && 或 ; 分隔符。

第 3 步：在 Node.js 代码中读取环境变量

在你的 JavaScript 或 TypeScript 代码中，直接通过全局对象 process.env 即可安全获取传入的变量值：

// build.js 示例代码
const currentEnv = process.env.NODE_ENV;
const apiBase = process.env.API_BASE || 'http://localhost:8080';

console.log(`[构建任务启动] 当前运行环境: ${currentEnv}`);
console.log(`[接口配置] API 基础路径: ${apiBase}`);

if (currentEnv === 'production') {
  console.log('正在执行生产环境专属混淆与压缩...');
} else {
  console.log('启用开发模式 SourceMap...');
}

第 4 步：跨端验证运行

无论是在 Windows 命令提示符（CMD）、PowerShell、macOS Terminal、Linux 云服务器，还是在 GitHub Actions / GitLab CI 的容器构建环境中，统一执行：

npm run build

命令均能正常解析环境变量并无差错启动，彻底杜绝了不同开发人员因操作系统不同而导致的构建失败问题。

进阶场景与现代原生替代方案

除了通用的 cross-env 方案外，针对不同的团队基建与 Node.js 版本，还有以下两种值得关注的实践路径：

1. Node.js 20.6.0+ 原生 --env-file 配置

从 Node.js v20.6.0 开始，官方引入了内置的环境文件解析标志 --env-file。这意味着如果你项目使用的 Node.js 版本较新，可以不再依赖任何第三方包，直接实现跨平台环境变量配置。

首先在项目根目录下创建环境配置文件，例如 .env.production：

# .env.production
NODE_ENV=production
PORT=8080
API_BASE=https://api.example.com

然后在 package.json 中直接利用 Node 原生参数加载该文件：

"scripts": {
  "build": "node --env-file=.env.production build.js"
}

由于 --env-file 是 Node.js 运行时层面的参数，它在 Windows、macOS 和 Linux 上均由 Node 自身统一解析，天然具备跨平台一致性，是现代 Node.js 项目不可忽视的轻量化选择。

2. 遇到管道符与通配符时使用 cross-env-shell

cross-env 默认只将环境变量传递给紧随其后的单个命令。如果你的 script 中包含了管道符（如 |）、重定向符（如 >）或者需要将环境变量当做参数拼接在后续命令中，直接使用 cross-env 可能会导致变量无法在管道后方生效。

针对这种情况，cross-env 软件包附带提供了名为 cross-env-shell 的专属命令：

"scripts": {
  "deploy": "cross-env-shell "NODE_ENV=production && node deploy.js | tee deploy.log""
}

cross-env-shell 会显式启动当前系统的 Shell 来完整解析整串复合语句，同时保障变量注入的正确性。

常见陷阱与排查避坑指南

"scripts": {
  "start": "cross-env APP_TITLE="My Application Dashboard" node server.js"
}

// 错误写法：在 JavaScript 中，非空字符串 "false" 转换为布尔值时恒为 true！
if (Boolean(process.env.DEBUG)) {
  console.log('调试模式已开启'); // 即使传了 false 也会执行！
}

// 正确写法：严格比对字符串内容
const isDebug = process.env.DEBUG === 'true';

各方案对比与技术决策矩阵

为了帮助大家在日常工程实践中做出最合理的架构选型，我们将目前主流的几种方案总结对比如下：