cross-env 常用命令

cross-env 是一个跨平台设置环境变量的工具，解决 Windows 和 macOS/Linux 下设置环境变量语法不一致的问题。

为什么需要 cross-env

在 package.json 中设置环境变量，不同系统语法不同：

{
  "scripts": {
    "start": "NODE_ENV=production node app.js"
  }
}

• macOS/Linux：正常工作
• Windows：报错（NODE_ENV 不是内部或外部命令）

使用 cross-env 可以统一写法，跨平台兼容。

安装

# 安装为开发依赖
npm install -D cross-env

# 如需锁定大版本（可选）
npm install -D cross-env@7

使用方式

在 package.json 中使用

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development node app.js",
    "build": "cross-env NODE_ENV=production vite build",
    "start": "cross-env NODE_ENV=production PORT=3000 node server.js"
  }
}

设置多个环境变量

{
  "scripts": {
    "start": "cross-env NODE_ENV=production API_URL=https://api.example.com PORT=3000 node server.js"
  }
}

配合其他工具使用

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development vite",
    "build": "cross-env NODE_ENV=production vite build",
    "test": "cross-env NODE_ENV=test jest",
    "lint": "cross-env NODE_ENV=development eslint src/"
  }
}

环境变量值包含空格

Windows 下环境变量值包含空格时，需要用双引号包裹：

{
  "scripts": {
    "greet": "cross-env GREETING=\"hello world\" node app.js",
    "title": "cross-env APP_NAME=\"My App\" node server.js"
  }
}

配合 npm run 传递参数

使用 -- 分隔符将参数传递给实际命令：

{
  "scripts": {
    "test": "cross-env NODE_ENV=test jest",
    "start": "cross-env NODE_ENV=production node server.js"
  }
}

# 传递参数给 jest（--watch 等）
npm test -- --watch

# 传递参数给 node
npm start -- --port 3001

# 多个参数
npm test -- --watch --coverage --bail 1

cross-env vs cross-env-shell

cross-env 提供两个命令：

命令	用途	示例
cross-env	执行单条命令	cross-env NODE_ENV=production node app.js
cross-env-shell	执行包含多条命令的 shell 脚本	cross-env-shell "echo $NODE_ENV && node app.js"

使用 cross-env-shell 的场景

当需要环境变量在整个 shell 脚本中生效时使用：

{
  "scripts": {
    "greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
  }
}

何时选择 cross-env-shell

• 命令中包含特殊 shell 字符（&&、||、| 等）
• 需要在 Windows 中捕获 SIGINT 信号（Ctrl+C）
• 需要使用 $VAR 语法引用环境变量（Windows 默认用 %VAR%）

cross-env-shell 的兼容性说明

cross-env-shell 内部通过 shell 执行命令，$VAR 语法在不同终端下行为不一致：

• Git Bash / WSL：正常工作
• CMD：$VAR 不会被展开，需要使用 %VAR%
• PowerShell：$VAR 可能被 PowerShell 自身解析，导致非预期行为

如果团队成员使用不同终端，建议避免在 cross-env-shell 中依赖 $VAR 引用，改用直接传值。

---

常见使用场景

Vue/React 项目

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development vite",
    "build": "cross-env NODE_ENV=production vite build",
    "preview": "cross-env NODE_ENV=production vite preview"
  }
}

测试环境

{
  "scripts": {
    "test": "cross-env NODE_ENV=test jest",
    "test:watch": "cross-env NODE_ENV=test jest --watch",
    "test:coverage": "cross-env NODE_ENV=test jest --coverage"
  }
}

指定 API 地址

{
  "scripts": {
    "dev": "cross-env VITE_API_URL=http://localhost:3000 vite",
    "dev:staging": "cross-env VITE_API_URL=https://staging-api.example.com vite",
    "dev:prod": "cross-env VITE_API_URL=https://api.example.com vite"
  }
}

设置 PATH 环境变量

用于临时指定工具或 Node.js 的路径：

{
  "scripts": {
    "start": "cross-env PATH=./node_modules/.bin:$PATH node app.js",
    "dev": "cross-env PATH=/usr/local/node-v18/bin:$PATH node server.js"
  }
}

⚠️ PATH 设置在 Windows 下行为不同，$PATH 语法仅在 cross-env-shell 中有效。

常见问题

环境变量不生效

确保环境变量放在 cross-env 之后、命令之前：

{
  "scripts": {
    "start": "cross-env NODE_ENV=production node app.js"
  }
}

配合 .env 文件

如果使用 Vite，可以使用 .env 文件代替 cross-env：

# .env
VITE_API_URL=https://api.example.com

# .env.staging
VITE_API_URL=https://staging-api.example.com

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "build:staging": "vite build --mode staging"
  }
}

💡 Vite 项目推荐使用 .env 文件，Node.js 项目推荐使用 cross-env。

项目状态

⚠️ cross-env 已于 2025-11-19 归档，不再接受新功能。当前功能稳定，可继续使用。

参考

• cross-env GitHub