如何在ViteJS/React中为不同部署环境加载对应.env文件？

一、明确Vite的.env加载规则 #

Vite通过MODE环境变量匹配对应.env文件，而非NODE_ENV或自定义ENV变量。默认加载优先级（从低到高）：

• .env：全局基础配置，所有环境通用
• .env.[MODE]：对应指定MODE的环境专属配置，优先级高于.env
• .env.local：本地私有配置（需加入.gitignore），优先级最高

你现有的.env.dev、.env.staging等文件可直接对应MODE=dev、MODE=staging等场景，无需修改命名。

二、Windows本地调试的环境变量设置方法 #

1. 临时命令行设置（单次生效） #

区分CMD和PowerShell语法：

• CMD：set MODE=staging && vite
• PowerShell：$env:MODE="staging"; vite

2. 写入package.json脚本（推荐） #

无需手动输入变量，直接在scripts中定义各环境的启动/构建命令：

{
  "scripts": {
    "dev:localhost": "MODE=localhost vite",
    "dev:dev": "MODE=dev vite",
    "dev:test": "MODE=test vite",
    "dev:staging": "MODE=staging vite",
    "build:dev": "MODE=dev vite build",
    "build:test": "MODE=test vite build",
    "build:staging": "MODE=staging vite build",
    "build:prod": "MODE=prod vite build"
  }
}

若Windows下直接用MODE=xxx报错，安装cross-env实现跨平台兼容：

• 安装命令：npm install cross-env --save-dev
• 修改脚本示例：

{
  "scripts": {
    "dev:staging": "cross-env MODE=staging vite",
    "build:staging": "cross-env MODE=staging vite build"
  }
}

3. 持久化全局设置 #

右键「此电脑」→「属性」→「高级系统设置」→「环境变量」，在用户变量中新增：

• 变量名：MODE
• 变量值：目标环境（如staging）
  设置完成后重启命令行/IDE，运行vite即可自动加载对应.env文件。

三、部署阶段的环境配置加载方案 #

1. CI/CD部署（GitHub Actions、GitLab CI等） #

在CI/CD的环境变量配置中添加MODE，对应部署环境后执行构建命令。示例（GitHub Actions）：

jobs:
  build-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装依赖
        run: npm install
      - name: 构建预发布环境
        run: npm run build:staging
        env:
          MODE: staging

2. 服务器直接部署 #

• Linux服务器：构建前指定MODE，如MODE=staging npm run build；或在~/.bashrc中添加export MODE=staging，执行source ~/.bashrc全局生效。
• Windows服务器：同本地调试方法，使用set MODE=staging && npm run build或cross-env兼容。

3. 容器化部署（Docker） #

• 在Dockerfile中定义：ENV MODE=staging
• 运行容器时指定：docker run -e MODE=staging your-image-name

四、验证环境变量加载状态 #

在代码中打印变量确认：

console.log('当前环境MODE:', import.meta.env.MODE);
console.log('API地址:', import.meta.env.VITE_API_URL);

注意：Vite仅暴露前缀为VITE_的变量到客户端代码，所以.env文件中需按VITE_XXX=xxx格式定义变量。

内容的提问来源于stack exchange，提问作者Dobromir Ivanov