先说结论Vue 的环境变量在构建时就被编译进 JS 文件Docker 的 ENV 变量在容器运行时才注入两者本来就是两条时间线的产物。你就算在 docker-compose 里写满了 VITE_APP_API_BASE前端页面打开时照样请求 localhost。想通这一层你就会明白网上那些“为啥 Docker 里配了环境变量前端就是读不到”的求助帖多半是卡在了构建期和运行期的错位上。这篇文章我会直接给出一套最小完整实践让你在 Vue 项目里干净地拿到 Docker 运行时传进来的环境变量。方案不挑打包器Vite 和 Vue CLI 都能用部署环境也不限Nginx 容器、K8s 里跑甚至 Docker Compose 起服务都能套用。内容适合正在做前端容器化的开发同学也适合已经在生产环境踩了坑、想找个稳妥方案的人。1. 为什么这个坑这么普遍1.1 Vue 环境变量的“隐藏规则”先花一分钟把 Vue 项目里的环境变量机制捋清楚。无论你用的是 Vue CLI 还是 Vite本质上都是“构建期间读变量构建之后变量消失”。Vue CLI基于 Webpack会把.env文件里的VUE_APP_XXX变量在构建时替换到代码里生成静态文件。Vite 则用.env文件里的VITE_XXX变量通过import.meta.env.VITE_XXX进行静态替换。这里的“替换”是物理替换——你在源码里面写import.meta.env.VITE_APP_API_BASE构建完的产物里就已经是一个具体的字符串了比如https://api.example.com。这就意味着构建产物一旦生成环境变量的“读取”动作就结束了之后浏览器里跑的 JS 不会再向操作系统或容器要任何环境变量。前端静态文件本质上就是一堆文本你把它丢到 Nginx、OSS、CDN 上都一样它本身没有“进程环境”的概念。1.2 Docker 环境变量与浏览器环境的错位Docker 的环境变量是容器进程运行时才存在的。你docker run -e VITE_APP_API_BASEhttps://api.example.com nginx-image重点是这个变量存在了 Nginx 主进程的环境里也可能存在了 shell 脚本的环境里但它不会自动出现在浏览器里。浏览器是你的电脑上运行的它访问 Nginx 拿到的只是 HTML、JS、CSS 等静态文件。这些文件里如果没有任何地方显式地把变量“放”进去浏览器端自然什么都拿不到。所以 Doker 环境变量和浏览器之间隔着一整条“运行时注入”的链路必须由容器里的某个进程在启动时负责把变量翻译成前端可读的静态资源。1.3 几种“看起来很对但实际有问题”的尝试我见过不少人在这个坑里绕比较典型的有这些操作在Dockerfile里写ENV VITE_APP_API_BASEhttps://api.example.com然后在RUN npm run build时使用。这种做法看着顺手但镜像一旦构建完变量就固定了。以后要换环境你得重新构建镜像这完全违背了容器“一次构建到处运行”的初衷。在nginx.conf里直接引用env VITE_APP_API_BASE然后用envsubst去替换。问题在于 Nginx 配置文件里本身就有$host、$uri这类运行时变量一个粗暴的envsubst会把它们全干掉配置直接失效。写了一个public/config.js试图在业务代码里读取里面的window.CONFIG。思路是对的但你把配置文件直接打进镜像容器运行时传进来的变量根本没有机会覆盖它结果依然无效。这些尝试有一个共同病根变量被写死在构建产物或镜像里了而不是在容器启动时“现做现卖”。2. 思路让运行时配置接管2.1 把构建期和运行期分开正确的做法是把环境变量分成两份构建期变量比如 NPM 源地址、构建时需要的版本号、是否需要压缩等这些只在构建阶段有用与运行时无关。运行期变量比如 API 地址、前端功能开关、站点标识等这些需要在容器启动时根据环境动态决定。Vue 项目在构建完成之后只有dist目录下的静态文件被真正使用。所以我们只需要在容器启动时往这个静态目录里额外生成一个前端可以加载的配置文件业务代码再去统一读取这个配置文件问题就解决了。2.2 用一个前端可读的 JS/JSON 文件承接变量我推荐的做法是生成一个env.js文件内容是window.APP_CONFIG { apiBase: https://api.example.com, featureFlag: new_dashboard };然后在 Vue 应用的入口 HTML 的head区域通过普通script标签提前加载它。这个文件路径是公开的浏览器加载它没有任何跨域问题JS 执行完会同步把配置挂到window.APP_CONFIG上。之后你的业务代码里就能随时取用。为什么要用 JS 文件而不是 JSON 文件因为如果直接用fetch(/config.json)前端必须等待异步请求返回才能初始化一不小心就是白屏闪一下。而script是同步阻塞加载的天然保证配置在应用代码执行前就位省掉一大堆时序问题。2.3 为什么推荐在容器 entrypoint 里做生成把配置生成逻辑放在 Nginx 镜像的entrypoint或docker-entrypoint.d脚本里而不是放在构建时核心点有这几个镜像保持环境无关测试、预发、生产环境可以直接复用同一个镜像。容器启动的时候脚本能从进程环境变量里取到值动态生成配置文件实现“配置随环境走”。也方便在 K8s 里去挂载 ConfigMap或者用 Docker Compose 的environment传参非常灵活。直接生成文件而不是去改现有文件思路上也更好理解启动时无中生有不依赖任何基础配置的“预埋”干净可控。3. 最小完整实践3.1 项目结构说明这套实践用到的关键文件就几个vue-project/ ├── public/ ├── src/ │ ├── main.js │ ├── App.vue │ └── config.js ├── index.html ├── Dockerfile └── docker-entrypoint.d/ └── 40-env-config.sh重点解释一下docker-entrypoint.d这个目录。官方 Nginx 镜像支持把*.sh脚本放进这个目录镜像启动时会按文件名顺序自动执行这是 Nginx 镜像的官方机制。我用40-开头只是想确保它在默认的15-、20-脚本之后执行避免和 Nginx 自带的初始化脚本冲突。3.2 前端侧代码怎么读取配置在src/config.js里写一个统一读取配置的封装// src/config.js const runtimeConfig window.APP_CONFIG || {}; const defaultConfig { apiBase: import.meta.env.VITE_APP_API_BASE || /api, featureFlag: import.meta.env.VITE_APP_FEATURE_FLAG || default, siteName: import.meta.env.VITE_APP_SITE_NAME || My App, }; export const config { ...defaultConfig, ...runtimeConfig, };这样设计的一个明显好处是开发环境没有env.js时自动降级到构建期变量生产环境一旦env.js被容器生成出来运行期变量自动覆盖缺省值。在main.js里你只需要正常引入import { config } from ./config; // 使用方式 console.log(config.apiBase);在index.html里提前加载外部配置!DOCTYPE html html langzh-CN head meta charsetUTF-8 / script src/env.js/script /head body div idapp/div script typemodule src/src/main.js/script /body /html如果你的项目是 Vue CLIWebpackimport.meta.env需要换一下。在src/config.js里改为const defaultConfig { apiBase: process.env.VUE_APP_API_BASE || /api, featureFlag: process.env.VUE_APP_FEATURE_FLAG || default, siteName: process.env.VUE_APP_SITE_NAME || My App, };其他逻辑完全一样。3.3 Dockerfile 设计用一个多阶段构建先出静态产物再放到 Nginx 镜像里。这是我生产环境用着很稳的组合# 构建阶段 FROM node:18-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 运行阶段 FROM nginx:1.25-alpine COPY --frombuild /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf COPY docker-entrypoint.d/40-env-config.sh /docker-entrypoint.d/40-env-config.sh RUN chmod x /docker-entrypoint.d/40-env-config.sh EXPOSE 80注意我并没有在 Dockerfile 里写任何ENV VITE_APP_XXX这种设置。镜像里不应该有环境相关的硬编码这点很关键。所有运行期变量都留到容器真正启动时再传入。3.4 entrypoint 脚本生成 env.js重点来了。容器启动时40-env-config.sh会执行把进程环境变量翻译成浏览器能读的env.js#!/bin/sh set -e cat /usr/share/nginx/html/env.js EOF window.APP_CONFIG { apiBase: ${VITE_APP_API_BASE:-/api}, featureFlag: ${VITE_APP_FEATURE_FLAG:-default}, siteName: ${VITE_APP_SITE_NAME:-My App} }; EOF这段脚本的思路非常直白使用 shell 的双引号让变量展开${VAR:-default}语法则是给变量一个安全的默认值。这样即使容器启动时没传环境变量前端也不会直接拿到undefined。实际使用中启动命令会变成这样docker run -d -p 8080:80 \ -e VITE_APP_API_BASEhttps://api.example.com \ -e VITE_APP_FEATURE_FLAGnew_dashboard \ -e VITE_APP_SITE_NAMEMy App \ my-vue-image:latest用 Docker Compose 的话对应的配置是services: web: image: my-vue-image:latest ports: - 8080:80 environment: - VITE_APP_API_BASEhttps://api.example.com - VITE_APP_FEATURE_FLAGnew_dashboard - VITE_APP_SITE_NAMEMy App3.5 Nginx 配置要点基础配置很简单server { listen 80; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } }有一个容易忽略的点env.js这个文件最好不要被浏览器缓存。如果 Nginx 给静态文件加了一周的Cache-Control每次改环境变量后重新部署用户浏览器里还挂着老配置体验非常糟糕。所以我在配置里单独把它拎出来location /env.js { add_header Cache-Control no-cache, no-store, must-revalidate; try_files $uri 404; }这样浏览器每次打开页面都会重新获取一份新的env.js配置自然就是最新的。其余静态资源因为带着文件指纹可以放心缓存互不影响。3.6 开发环境怎么模拟本地开发时容器这套机制不生效。为了让开发环境和生产环境的一致性更高我建议在本地手动创建一个public/env.js// public/env.js window.APP_CONFIG { apiBase: http://localhost:3000/api, featureFlag: local_dev, siteName: Local App, };因为 Vue CLI 和 Vite 会把public目录下的内容原样复制到构建产物里本地开发服务器也会直接把它当作静态资源提供给浏览器所以开发环境加载/env.js是完全没问题的。需要提醒的是这个public/env.js文件不应该提交到代码仓库建议加到.gitignore里。否则一个不留神把本地地址带到生产镜像里就是个不小的隐患。4. 避坑与踩坑记录4.1 缓存问题改配置不生效我先前就吃过这个亏。当时改完docker run的环境变量重新部署打开页面看到的还是旧 API 地址。排查到最后发现是浏览器对/env.js做了缓存Nginx 返回的响应头里还带着Cache-Control: max-age3600。解决办法就是前面说的在 Nginx 单独特意处理一下/env.js的请求加上no-cache。如果已经上线了你可以在开发者工具里勾选 Disable cache 后强制刷新等部署新配置后自然恢复。4.2 特殊字符导致脚本生成失败shell 脚本生成 JS 文件最怕变量值里出现单引号、双引号、$、换行这类特殊字符。比如 API 地址如果带了个$符号shell 可能会自动做变量替换或者截断最后生成的env.js就是一个语法错误的文件。最稳妥的办法是使用 Node 来生成配置文件让转义问题交给 Node 处理。在容器里如果有node环境你可以这样写#!/bin/sh set -e node -e const fs require(fs); const config { apiBase: process.env.VITE_APP_API_BASE || /api, featureFlag: process.env.VITE_APP_FEATURE_FLAG || default, siteName: process.env.VITE_APP_SITE_NAME || My App }; const content window.APP_CONFIG ${JSON.stringify(config, null, 2)};; fs.writeFileSync(/usr/share/nginx/html/env.js, content); 如果你的运行镜像里有jq也可以把变量拼成 JSONjq -n \ --arg api $VITE_APP_API_BASE \ --arg flag $VITE_APP_FEATURE_FLAG \ {apiBase: $api, featureFlag: $flag} \ /usr/share/nginx/html/env.json不过我还是倾向于 JS 文件因为省掉了前端异步请求的那一步。Node 方案在 Nginx 基础镜像里并不自带你需要把这个脚本放到构建阶段或者选用带 Node 的运行镜像这个看你的实际镜像策略来定。4.3 变量在构建期被“焊死”的惯性思维很多人在做运行时配置时下意识还是会在代码里直接用import.meta.env.VITE_APP_API_BASE。这个习惯本身不是错的但你要形成条件反射只要变量需要在容器运行时动态变化它就不能只依赖import.meta.env或process.env必须走window.APP_CONFIG这一层。构建期变量只适合做默认值。我见过一个团队把.env文件里的地址和 Docker 环境变量同时传了两份最后前端实际生效的是构建期变量因为代码里直接取了import.meta.env。他们查了半天最后才发现代码里根本没有包一层运行时配置。这个问题本质上是“默认值和运行时值的优先级搞颠倒了”。4.4 在老项目里加配置容易忽略 HTML 插法如果你的项目用了模板比如index.html是通过某个后端模板引擎输出的那就要注意脚本标签的加载位置。env.js必须放在你的业务代码之前加载否则业务代码执行时window.APP_CONFIG还是空的。顺序错了配置读不到是必然的。最简单的验证方法是打开浏览器控制台输入window.APP_CONFIG看能不能输出对象。如果输出undefined要么文件没生成要么 script 顺序不对。4.5 在 Kubernetes 里怎么玩K8s 环境里容器启动时的那套 entrypoint 脚本也能正常工作。你只需要把 ConfigMap 里的键值对映射成环境变量再部署 Pod 即可。因为脚本读取的是进程环境变量所以本质上是把 env 机制平移过来不需要改代码。还有一种更“K8s native”的做法不通过 entrypoint 生成直接用一个 ConfigMap 挂载/usr/share/nginx/html/env.js。但这样做有个缺点ConfigMap 的内容必须先由运维手动整理少了一层动态生成的便利。作为最小实践我建议还是让 entrypoint 统一生成这样无论在哪个平台行为都一样。5. 更稳妥的优化方向5.1 接入 TypeScript 时的类型定义如果项目用了 TypeScriptwindow.APP_CONFIG需要做一下类型声明否则window上挂自定义属性会报 TS 错误。在src/types/env.d.ts里加一段interface Window { APP_CONFIG?: { apiBase?: string; featureFlag?: string; siteName?: string; }; }这种做法成本低还能让团队成员对配置结构一目了然。如果新增一个变量类型声明里也会自动提醒哪些地方需要同步更新。5.2 配置项多到爆炸时怎么办如果运行期配置不只是三四个而是十几个甚至更多我建议不要全部塞在环境变量里否则 shell 脚本会变得非常啰嗦。你可以改为让容器进程从某个专门的主机配置文件里读取再合并环境变量覆盖。不过对于大多数 Vue 项目三到五个运行期变量已经足够不需要过度设计。5.3 后端接口地址动态切换的实践场景这套方案最适合的场景是同一套前端镜像在多个环境部署。比如测试环境、预发环境、生产环境的 API 地址各不相同但前端代码和镜像完全一致。部署的时候只要传入不同的VITE_APP_API_BASE启动出来的容器就能各自对接不同后端非常友好。我测试过一个真实场景国内某测试集群和后端联调时直接docker run -e VITE_APP_API_BASEhttp://10.10.x.x:8080/api起来一个临时容器改完配置删掉再起全程不用重新打包效率比构建时替换高太多了。5.4 环境变量里的密钥安全提示最后说一个容易被忽略的安全点任何传到前端的环境变量都等于公开信息。因为浏览器加载env.js时任何人都能看到里面的明文内容。不要指望把它当成后端密钥来用比如数据库密码、服务端密钥绝对不能放进来。正确姿势是前端需要密钥时由后端提供一个受控的接口或者通过短时令牌去换取。前端只保留一些“公开但需要区分环境”的配置比如 API 域名、埋点 ID、功能开关。理解清这道边界你在设计配置体系时就不会踩到安全红线。6. 实际使用的一些体会这套最小实践我用了很久期间踩过不少坑但最终的结论依然很简单不要试图在构建期的壳里塞运行期的变量。让容器启动时生成env.js前端通过window.APP_CONFIG统一读取一条命令就能切换环境镜像可以保持环境无关。这种模式在单机 Docker、Docker Compose、K8s 集群里都能直接跑不需要为不同平台写出两套逻辑。如果你现在正被“Vue 拿不到 Docker 环境变量”这个问题卡住我建议你直接按文中的方案落地一次。先不要加各种花哨的配置管理组件最小的一套能跑通再说。等跑通了你再去扩展变量加密、平台自定义配置等高级玩法思路会顺很多。