使用 cross-env 配置多环境变量：Vue、React、Angular 全指南

在开发前端项目时，管理不同环境（开发、测试、生产）的变量是常见的需求。cross-env 是一个跨平台的环境变量设置工具，能帮助开发者在不同操作系统（如 Windows、macOS、Linux）中统一配置环境变量。本文将详细介绍 cross-env 的安装与使用，并覆盖 Vue2、Vue3、React、Angular 四大框架的具体配置方法。

 

---

一、什么是 cross-env？

cross-env 解决了不同操作系统下环境变量设置的兼容性问题。例如，在 Windows 中设置环境变量需使用 SET NODE_ENV=production，而 macOS/Linux 使用 export NODE_ENV=production。通过 cross-env，开发者只需一条命令即可跨平台运行，无需关注系统差异112。

 

---

 

二、安装 cross-env

在所有框架中，安装方式一致：

npm install --save-dev cross-env

 

---

三、通用配置方法

1. 配置 package.json 脚本

在 package.json 的 scripts 字段中，通过 cross-env 定义环境变量。例如：

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

• NODE_ENV 是常用变量，用于标识当前环境（development、production 等）。

2. 在代码中读取变量

通过 process.env.NODE_ENV 或其他自定义变量（如 VUE_APP_API_URL）获取值。
注意：部分框架对变量名有特定要求（如 Vue 要求以 VUE_APP_ 开头）

 

---

 

四、框架专属配置

1. Vue2 项目

步骤 1：配置环境文件

• 在项目根目录创建 .env.development 和 .env.production 文件：

  # .env.development
  VUE_APP_API_URL = http://localhost:3000
  

  # .env.production
  VUE_APP_API_URL = https://api.example.com
  

步骤 2：修改 package.json

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development vue-cli-service serve",
    "build": "cross-env NODE_ENV=production vue-cli-service build"
  }
}

步骤 3：代码中访问变量

console.log(process.env.VUE_APP_API_URL);

　　

---

 

2. Vue3 项目（基于 Vite）

步骤 1：配置环境文件

• 创建 .env.localhost,.env.development 和 .env.production 文件：

  # .env.localhost
  VITE_API_URL = http://localhost:3000
  VITE_APP_ENV = 'localhost'
  

  　　

  # .env.development
  VITE_API_URL = http://test.com
  VITE_APP_ENV = 'development'

　　　注意：Vite 默认以 VITE_ 开头的变量才会暴露给客户端。

步骤 2：修改 package.json（自定义额外变量）

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development vite", //测试环境
　  "dev:liMing": "cross-env VITE_USER_ID=158745 vite --mode localhost", // 本地环境
    "build": "cross-env NODE_ENV=production vite build"
  }
}　

　

步骤 3：代码中访问变量

// 本地环境
console.log(import.meta.env.VITE_API_URL); // http://localhost:3000
console.log(import.meta.env.VITE_USER_ID); // 158745
console.log(import.meta.env.VITE_APP_ENV); // localhost

// 测试环境
console.log(import.meta.env.VITE_API_URL); // http://test.com
console.log(import.meta.env.VITE_APP_ENV); // development

　　

3. React 项目（基于 Create React App）

步骤 1：配置环境文件

• 创建 .env.development 和 .env.production 文件：

  # .env.development
  REACT_APP_API_URL = http://localhost:3000
  

　　　注意：React 要求变量以 REACT_APP_ 开头。

步骤 2：修改 package.json

{
  "scripts": {
    "start": "cross-env NODE_ENV=development react-scripts start",
    "build": "cross-env NODE_ENV=production react-scripts build"
  }
}　

步骤 3：代码中访问变量

console.log(process.env.REACT_APP_API_URL);

 

---

 

4. Angular 项目

步骤 1：配置环境文件

在 src/environments 目录下创建 environment.ts 和 environment.prod.ts：

// environment.ts（开发环境）
export const environment = {
  production: false,
  API_URL: 'http://localhost:3000'
};

　　

// environment.prod.ts（生产环境）
export const environment = {
  production: true,
  API_URL: 'https://api.example.com'
};

　　

步骤 2：修改 angular.json

在 angular.json 的 configurations 中指定环境文件：

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "configurations": {
            "production": {
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ]
            }
          }
        }
      }
    }
  }
}

　　

步骤 3：代码中访问变量

import { environment } from '../environments/environment';
console.log(environment.API_URL);

　　

---

 

五、常见问题与技巧

1. 变量未生效

   • 检查变量名是否符合框架要求（如 VUE_APP_、REACT_APP_）112。

   • 重启开发服务器（环境变量通常在启动时加载）。

2. 多环境扩展
   可通过自定义变量名区分更多环境（如 NODE_ENV=staging），并创建对应的 .env.staging 文件12。

3. 安全提示

• 敏感信息（如 API 密钥）不应暴露在前端代码中，应通过后端服务中转。

• 生产环境变量需避免硬编码，推荐使用 CI/CD 工具动态注入5。

 

---

 

六、总结

通过 cross-env，开发者可以轻松管理多环境变量，无需担心跨平台兼容性问题。无论是 Vue、React 还是 Angular，核心逻辑均遵循以下步骤：

1. 安装 cross-env；

2. 配置 package.json 脚本；

3. 创建环境文件或使用框架内置环境管理；

4. 在代码中按需读取变量。

通过以上方法，即使是初级开发者也能快速上手多环境配置，提升开发效率。