Vue 3 项目在开发环境中运行流畅，一旦交付到测试或生产服务器，总会遇到 Node 版本不一致、依赖缺失、编译产物路径错乱等问题。Docker 通过将应用及其运行环境打包成一个标准化的镜像，可以彻底解决这种“环境漂移”。在容器化实践中，我们不仅要关注如何把 Vue 3 打包产物放进容器，还要考虑构建效率、镜像体积、运行时配置的灵活性和安全性，让整个交付过程既轻量又可靠。接下来，我们将从 Dockerfile 的编写入手，逐步构建一个生产可用的 Vue 3 Docker 镜像。
多阶段构建：分离构建与运行环境
一个常见的误区是直接把整个 Vue 3 源码拷贝到容器中，然后安装全部依赖并执行构建，最后在同一个镜像里用开发服务器去启动。这样做会导致最终镜像体积庞大，而且镜像中残留了大量源码和 node_modules，不仅浪费存储空间，还增加了潜在的安全风险。Docker 的多阶段构建特性可以优雅地解决这个问题。
多阶段构建允许我们在一个 Dockerfile 中定义多个 FROM 指令，每个阶段可以使用不同的基础镜像。第一阶段负责编译构建，第二阶段只提取构建产物并运行一个轻量的 Web 服务器。下面是一个典型的 Vue 3 + Vite 项目的多阶段 Dockerfile 示例：
# 第一阶段：构建 FROM node:18-alpine AS build-stage WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 第二阶段：生产运行 FROM nginx:stable-alpine AS production-stage COPY --from=build-stage /app/dist /usr/share/nginx/html EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]
第一阶段使用 node:18-alpine 作为基础镜像，利用 Alpine 的轻量特性减少层体积。先单独复制 package.json 文件并执行 npm ci，这样可以利用 Docker 的层缓存机制，当依赖未变化时，后续构建就可以跳过依赖安装步骤，大幅提升 CI/CD 的速度。第二阶段选用 nginx:stable-alpine，体积仅有几十 MB，远比带 Node 的镜像小得多。通过 COPY --from=build-stage 指令只把 dist 目录复制到 Nginx 的静态文件目录，最终镜像不会携带任何 Node 运行时和源代码，既安全又高效。
镜像体积与构建缓存优化
在容器化实践中，镜像体积直接影响拉取和部署速度。除了多阶段构建，还可以通过 .dockerignore 文件来排除不必要的文件进入上下文。在项目根目录创建 .dockerignore，内容可以包含 node_modules、.git、dist 以及本地环境变量文件等，避免 Docker 引擎将这些无关文件发送到守护进程，从而加快构建速度并防止敏感信息意外打包进镜像。
另一个容易被忽视的细节是基础镜像的选择。Node 官方提供了 alpine、slim 等多种变体，alpine 体积最小，但基于 musl libc，某些依赖可能存在兼容性问题。对于 Vue 3 工程，vite 和大部分插件在 Alpine 上都能正常工作，因此推荐使用 node:18-alpine。如果项目中用到了需要编译原生模块的依赖，可以先尝试在 alpine 中安装构建工具，如果仍存在问题，再考虑使用基于 Debian 的 slim 版本，但要注意镜像大小会因此增加百 MB 以上。
此外，Dockerfile 指令的顺序也会影响缓存复用。尽量把不易变动的指令放在前面，比如先复制 package.json 并安装依赖，再复制源代码。如果源代码频繁变更，依赖层则可以保持缓存命中，构建速度能提升数倍。
运行时配置：动态注入与 Nginx 调优
Vue 3 应用在部署到不同环境时，经常需要切换 API 地址、WebSocket 端点等配置。由于 dist 目录下的静态文件是在构建阶段生成的，一旦打包完成，其中的环境变量就被写死了。为了在运行时灵活变更配置，可以采用 Docker 的入口脚本方案。在镜像中增加一个启动脚本，该脚本在容器启动时读取环境变量，并将其注入到 JavaScript 文件或全局变量中，然后再启动 Nginx。
一种常见做法是创建一个 /docker-entrypoint.sh 脚本，内容大致如下：
#!/bin/sh
# 创建或覆盖配置文件，将环境变量注入 index.html 的全局 script
cat < <EOF > /usr/share/nginx/html/config.js
window.__APP_CONFIG__ = {
VITE_API_BASE_URL: "${VITE_API_BASE_URL}",
VITE_WS_ENDPOINT: "${VITE_WS_ENDPOINT}"
};
EOF
exec nginx -g "daemon off;"
然后在 index.html 的 <head> 中引入 <script src="/config.js"></script>，这样 Vue 应用就可以通过读取 window.__APP_CONFIG__ 来获取环境变量。这种方式不需要重新构建镜像，只需在启动容器时传入不同的环境变量即可适配多套环境，并且避免了将敏感配置硬编码在镜像中。
对于 Nginx 本身，也需要根据 Vue 3 单页面应用的特点做一些优化。由于 Vue Router 通常使用 history 模式，所有路由必须指向 index.html，否则刷新页面会出现 404。可以在 Nginx 配置文件中加入 try_files 指令：
server {
listen 80;
server_name localhost;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
try_files $uri $uri/ /index.html;
}
# gzip 压缩优化
gzip on;
gzip_types text/plain application/javascript text/css;
}
开启 gzip 压缩可以大幅减少静态资源的传输体积，进一步提高首次加载速度。同时，还可以设置合理的缓存头，对带有哈希值的 JS、CSS 文件进行长时缓存，而 index.html 设为不缓存，保证每次部署后用户都能获取最新版本。
容器编排与 CI/CD 集成
当 Vue 3 应用需要与其他后端服务一起部署时，可以使用 Docker Compose 来定义和运行多容器应用。一个典型的 docker-compose.yml 文件可能包含前端 Nginx 服务和后端 API 服务，利用网络别名让前端通过服务名访问后端，无需硬编码 IP 地址。例如：
version: '3'
services:
frontend:
build: ./frontend
ports:
- "80:80"
environment:
- VITE_API_BASE_URL=http://api:3000
api:
build: ./backend
ports:
- "3000:3000"
通过环境变量将后端地址设为 http://api:3000，这里的 api 就是 Docker Compose 网络中的服务名，实现了服务发现和配置解耦。
在持续集成流水线中，Docker 同样扮演着核心角色。以 GitHub Actions 为例，可以在 workflow 中增加构建镜像、推送到镜像仓库（如 Docker Hub 或私有 Registry）的步骤，然后在部署阶段直接拉取镜像运行。多阶段构建在 CI 环境中的缓存效果尤为明显，通过缓存 node_modules 和 Docker 层，每次构建时间可以从几分钟缩短到几十秒。结合动态环境变量注入，同一个镜像可以部署到开发、测试和生产环境，真正做到一次构建，处处运行。
工程化 Docker 实践并不是简单地写一个 Dockerfile，而是需要从构建效率、镜像安全、运行时灵活性和自动化交付等多个维度综合考虑。掌握这些技巧后，Vue 3 项目的交付将变得更加可控和可靠，团队也能把更多精力放在业务开发上。