React CI/CD中服务器端.env文件配置问题

核心结论 #

构建时Vite需要读取对应环境的配置变量，所以服务器/构建环境中必须存在这些变量的来源——要么是对应的.env文件，要么是通过其他方式注入的环境变量。针对你的情况，给出以下可行方案：

方案1：手动上传.env文件到服务器 #

这是最直接的解决方式，操作步骤如下：

• 将本地的.env.production/.env.qa文件上传到服务器的项目根目录（即你运行构建命令的目录）。
• 确保你的构建脚本指定了正确的环境模式，比如在package.json中配置：

  "scripts": {
    "build:prod": "vite build --mode production",
    "build:qa": "vite build --mode qa"
  }
  

• 运行对应构建命令时，Vite会自动读取同目录下的.env.production/.env.qa文件。
• 注意：设置好文件权限，确保服务器进程能读取该文件（比如设置权限为644）。

方案2：替代GitLab CI/CD单变量的方案（解决长度限制） #

如果不想手动上传文件，可以用GitLab的文件变量绕过单个变量的长度限制：

1. 在GitLab项目的Settings > CI/CD > Variables中，点击「Add variable」。
2. 选择变量类型为File，变量名设为ENV_PROD_FILE（或对应环境的名称），然后将本地.env.production的完整内容粘贴到内容框中。
3. 在.gitlab-ci.yml的构建阶段，先将文件变量写入项目根目录，再执行构建：

   build_prod:
     stage: build
     script:
       - cp "$ENV_PROD_FILE" .env.production
       - npm install
       - npm run build:prod
   

这种方式相当于在CI构建环境中动态生成了所需的.env文件，完美避开单个变量的长度限制。

方案3：服务器系统环境变量注入 #

如果是自己管理的服务器，可以直接在服务器上设置全局环境变量，Vite会自动读取前缀为VITE_的变量（Vite默认只将此类变量暴露到客户端代码）：

• 编辑服务器的bash配置文件（比如~/.bashrc或/etc/profile），添加需要的变量：

  export VITE_API_BASE_URL="https://prod-api.example.com"
  export VITE_APP_KEY="your-long-key-here"
  

• 执行source ~/.bashrc使配置生效，之后运行构建命令时，Vite会直接读取这些系统环境变量，无需存在.env文件。
• 注意：如果服务器部署多个项目，要避免变量名冲突。

整体流程梳理 #

1. 本地开发：本地创建各环境.env文件并加入.gitignore，运行vite --mode [环境名]时，Vite自动读取对应.env文件，所以本地运行正常。
2. 构建阶段：Vite需要获取环境变量来替换代码中的变量引用，因此构建环境（服务器/CI）必须有变量来源——要么是对应.env文件，要么是已注入的系统/CI环境变量。
3. 关键逻辑：Vite的环境变量读取优先级为：系统环境变量 > .env.[mode].local > .env.[mode] > .env.local > .env，只要构建环境中存在优先级更高的变量来源，就能正常完成构建。

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