Docker化Vite React应用无法读取自定义环境变量问题

核心问题根源 #

1. Vite环境变量注入时机限制
   Vite的import.meta.env变量是在npm run build构建阶段被静态替换进代码的，容器运行时设置的环境变量无法影响已构建完成的静态文件。你在容器内看到的环境变量属于运行时变量，和构建阶段无关。

2. 自定义环境变量命名规则不匹配
   Vite默认仅暴露前缀为VITE_的自定义环境变量，你使用的REACT_APP_是Create React App（CRA）的规则，Vite不会识别这类前缀的变量，自然不会注入到import.meta.env中。

3. Docker构建参数传递顺序错误
   如果Dockerfile中把ARG转ENV的步骤放在npm run build之后，构建过程根本无法读取到变量，导致注入失败。

修复步骤 #

1. 统一环境变量前缀 #

将所有自定义环境变量的前缀改为VITE_，比如VITE_BACKEND_URL1、VITE_BACKEND_URL2。

2. 确保构建阶段获取到变量 #

Dockerfile配置示例

FROM node:18-alpine as builder

# 定义构建参数
ARG VITE_BACKEND_URL1
ARG VITE_BACKEND_URL2

# 构建前将参数转为环境变量，让Vite构建时能读取
ENV VITE_BACKEND_URL1=$VITE_BACKEND_URL1
ENV VITE_BACKEND_URL2=$VITE_BACKEND_URL2

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
# 执行构建（此时已能读取到环境变量）
RUN npm run build

# 部署镜像
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

docker-compose.yml配置示例

通过build.args传递构建参数，确保变量能传入Dockerfile：

version: '3.8'
services:
  react-app:
    build:
      context: .
      args:
        VITE_BACKEND_URL1: "http://backend1.example.com"
        VITE_BACKEND_URL2: "http://backend2.example.com"
    ports:
      - "8080:80"

3. 验证变量注入效果 #

修改App.tsx打印变量：

function App() {
  console.log('后端URL1:', import.meta.env.VITE_BACKEND_URL1);
  console.log('所有环境变量:', import.meta.env);
  return <div>查看控制台获取环境变量</div>;
}

export default App;

重新构建并启动容器：

docker-compose down && docker-compose build --no-cache && docker-compose up

访问localhost:8080查看控制台，即可看到自定义环境变量。

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