使用Vite创建的React项目build命令未替换环境变量问题

问题复盘 #

开发环境执行npm run dev时环境变量正常生效，但执行npm run build时import.meta.env.VITE_API_URL未被替换为静态值，仅当存在.env.production文件时才能正常替换，希望直接通过终端/容器环境变量完成构建。

核心原因 #

Vite生产构建时，只会替换构建阶段进程能读取到的、以VITE_为前缀的环境变量。直接通过终端/容器设置变量时，若构建进程未正确读取到变量，或变量不符合命名规范，就会出现替换失败的情况。

解决方案 #

1. 严格遵守环境变量命名规范 #

所有需要Vite替换的环境变量必须以VITE_开头，比如VITE_API_URL，非该前缀的变量Vite不会进行静态替换。

2. 构建时正确传递环境变量 #

根据不同环境，在构建命令前注入变量：

• Linux/macOS终端：

  VITE_API_URL=https://your-api-domain.com npm run build
  

• Windows CMD：

  set VITE_API_URL=https://your-api-domain.com && npm run build
  

• PowerShell：

  $env:VITE_API_URL="https://your-api-domain.com"; npm run build
  

• 容器构建（Docker）：
  可以在Dockerfile中提前注入变量后执行构建：

  FROM node:18-alpine
  WORKDIR /app
  COPY package*.json ./
  RUN npm install
  COPY . .
  ENV VITE_API_URL=https://your-api-domain.com
  RUN npm run build
  

  或者运行容器时动态传递：

  docker run -e VITE_API_URL=https://your-api-domain.com your-image-name
  

3. 检查Vite配置是否干扰默认行为 #

如果vite.config.js中自定义了define配置，手动覆盖import.meta.env相关字段会导致Vite忽略环境变量注入，比如以下错误配置需要删除：

// 错误示例，需移除
export default defineConfig({
  define: {
    'import.meta.env.VITE_API_URL': JSON.stringify('fixed-value'),
  }
})

保持Vite默认的环境变量处理逻辑即可。

4. 验证环境变量是否被正确读取 #

在vite.config.js中添加日志，确认构建进程能获取到变量：

console.log('构建时VITE_API_URL:', process.env.VITE_API_URL);
export default defineConfig({
  // 你的配置
})

执行构建命令时查看控制台输出，若能打印出正确的变量值，说明Vite可以正常读取并替换。

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