如何从Dockerfile向基于Vite的Vue 3应用传递环境变量？

正在构建基于Vite的Vue 3应用，计划部署到Docker容器，需要从Dockerfile传递环境变量到应用代码中使用。当前Dockerfile配置如下：

# build stage
FROM node:lts-alpine as build-stage
WORKDIR /app
COPY package*.json ./

ARG VITE_API_URL_ARG=http://localhost:8080
ENV VITE_API_URL=$VITE_API_URL_ARG

RUN npm install
COPY . .
RUN npm run build

# production stage
FROM nginx:stable-alpine as production-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

同时在项目根目录添加了.env文件并设置VITE_API_URL=https://url，但本地运行时，在自定义组件中通过console.log(import.meta.env.VITE_API_URL)获取到的值是undefined。使用的依赖版本：vue ^3.2.47，vite ^4.3.4。

本地运行变量为undefined的解决步骤 #

• 确认.env文件位置与命名：必须放在项目根目录，文件名严格为.env（开发环境也可使用.env.development，优先级更高），不能有拼写错误。
• 检查变量定义格式：变量不能带空格，正确写法是VITE_API_URL=https://url，避免写成VITE_API_URL = https://url（等号两侧空格会导致识别失败）。
• 重启开发服务：Vite仅在启动时加载.env文件，修改后必须重启npm run dev，否则新变量不会生效。
• 排查优先级更高的.env文件：如果存在.env.local、.env.development.local，这些文件优先级高于.env，会覆盖原有变量，确认这些文件未重新定义VITE_API_URL。

Docker环境变量传递的修正方案 #

当前Dockerfile存在逻辑问题：COPY . .会把本地.env文件复制到容器中，可能覆盖Dockerfile设置的环境变量，可通过以下两种方式修正：

方案1：调整构建顺序，确保环境变量覆盖本地配置 #

修改Dockerfile，将环境变量设置放在COPY . .之后，保证构建时使用Docker的变量：

# build stage
FROM node:lts-alpine as build-stage
WORKDIR /app
COPY package*.json ./
RUN npm install

# 先复制源码，再设置环境变量执行构建
COPY . .

ARG VITE_API_URL_ARG=http://localhost:8080
ENV VITE_API_URL=$VITE_API_URL_ARG

RUN npm run build

# production stage
FROM nginx:stable-alpine as production-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

构建镜像时可自定义API地址：

docker build --build-arg VITE_API_URL_ARG=https://prod-api.example.com -t vue-app .

方案2：构建时忽略本地.env文件（推荐） #

在项目根目录创建.dockerignore文件，添加以下内容，避免本地环境文件干扰容器构建：

.env
.env.local
.env.development
.env.production

验证方法 #

• 本地运行：重启npm run dev后，查看控制台打印的import.meta.env.VITE_API_URL是否正确，或检查Vite启动日志中是否加载了目标.env文件。
• Docker部署：启动容器后，打开浏览器控制台，确认变量值为构建时传递的地址。

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