Nuxt3环境变量Docker配置详解

本文深入解析了在 Nuxt 3 静态站点生成（SSG）模式下，如何通过 Docker 的 `ARG` 和 `--build-arg` 在构建阶段精准注入环境变量（如 `NUXT_ENV_N_API`），彻底解决因混淆构建时与运行时上下文导致的 `process.env` 读取失效、变量始终回退默认值等高频痛点；文章手把手指导修改 Dockerfile 声明构建参数、调整 docker-compose 的 `args` 配置、保持 nuxt.config.ts 简洁可靠，并强调安全边界与 CI/CD 最佳实践，助你实现 Staging 与 Production 环境的真正隔离与可复现部署。

本文详解如何在 Nuxt 3（Vue 3）应用中，通过 Docker 构建阶段正确传递和使用环境变量（如 NUXT_ENV_N_API），解决 runtimeConfig.public 在构建时无法读取 process.env 的常见问题。

本文详解如何在 Nuxt 3（Vue 3）应用中，通过 Docker 构建阶段正确传递和使用环境变量（如 NUXT_ENV_N_API），解决 runtimeConfig.public 在构建时无法读取 process.env 的常见问题。

在 Nuxt 3 中，环境变量的注入时机至关重要：nuxt.config.ts 是在构建（build/generate）阶段执行的 Node.js 脚本，此时仅能访问构建时可用的环境上下文（即 Docker 的 ARG 或 CI 的构建参数），而非运行时容器的 ENV 变量。你遇到的问题——process.env.NUXT_ENV_N_API 始终回退到默认值——正是由于将变量错误地配置为运行时 environment，而未在构建阶段注入所致。

✅ 正确做法：使用 ARG + --build-arg 注入构建时变量

Docker 的 ARG 指令定义构建参数，可在 RUN 阶段被 docker build 通过 --build-arg 显式传入，并在构建上下文中被 Node.js 进程（如 npm run generate）读取。而 environment 仅作用于容器启动后，对 nuxt.config.ts 的执行毫无影响。

? 修改 Dockerfile（关键：声明 ARG 并确保在构建阶段生效）

FROM node:16.13.0 AS build-stage

# 声明构建参数（必须放在 FROM 之后、COPY 之前）
ARG NUXT_ENV_N_API
ARG NUXT_ENV_SETUP
ARG NUXT_ENV_VR_API

WORKDIR /app
COPY . .

# 此处 process.env 将能读取到传入的 ARG 值
RUN npm install
RUN npm run generate

FROM nginx AS runner-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
COPY --from=build-stage /app/default.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

? 提示：ARG 声明本身不赋值，需在 docker build 时通过 --build-arg KEY=VALUE 或 docker-compose 的 args 字段传入。

? 更新 docker-compose-staging.yml（移除 environment，改用 args）

version: '3'
services:
  frontend:
    container_name: frontend
    build:
      context: .
      dockerfile: Dockerfile
      args:  # ← 构建时传参，供 nuxt.config.ts 使用
        NUXT_ENV_SETUP: "staging"
        NUXT_ENV_N_API: "https://staging-url/api"
        NUXT_ENV_VR_API: "https://staging-v-url/api"
    ports:
      - "3005:80"
    volumes:
      - /app/node_modules
      - .:/app
    # ❌ 移除 environment: 下的所有 NUXT_ENV_* —— 它们对构建无意义

同理更新 docker-compose.yml（production 版本），仅修改 args 值即可。

⚙️ Nuxt 配置保持简洁可靠（无需额外处理）

你的 nuxt.config.ts 写法本身是正确的，只需确保变量名与 ARG 名一致：

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      baseURL: process.env.NUXT_ENV_N_API || 'https://production-url/api',
      vrUrl: process.env.NUXT_ENV_VR_API || 'https://production-v-url/api',
      setup: process.env.NUXT_ENV_SETUP || 'production',
      version: packageJSON.version
    }
  }
})

✅ 构建时 process.env.NUXT_ENV_N_API 将真实取到 --build-arg 传入的值；
✅ 生成的静态文件（dist/）中，runtimeConfig.public 已固化对应环境值；
✅ 最终 Nginx 容器无需任何环境变量即可运行（纯静态部署）。

⚠️ 注意事项与最佳实践

• 命名规范：Nuxt 3 推荐使用 NUXT_PUBLIC_* 前缀自动暴露至客户端（如 NUXT_PUBLIC_API_BASE），但若需兼容现有命名（如 NUXT_ENV_N_API），请确保其在 runtimeConfig.public 中显式映射，且不依赖 .env 文件（.env 仅在本地开发有效，Docker 构建中不可见）。
• 安全边界：所有通过 runtimeConfig.public 暴露的变量都会内联进客户端 JavaScript，请勿存放敏感信息（如密钥、token）。
• CI/CD 集成：在 GitHub Actions/GitLab CI 中，应使用 --build-arg 直接传参，例如：

  docker build \
    --build-arg NUXT_ENV_SETUP=staging \
    --build-arg NUXT_ENV_N_API=https://staging-url/api \
    -t my-nuxt-app .

• 验证方式：在 nuxt.config.ts 中临时添加日志（注意：仅构建时输出）：

  console.log('[BUILD] NUXT_ENV_SETUP:', process.env.NUXT_ENV_SETUP)

通过以上调整，你的 Staging 与 Production 构建将真正实现环境隔离，变量注入准确无误——这是 Nuxt 3 静态站点生成（SSG）模式下环境管理的标准实践。

到这里，我们也就讲完了《Nuxt3环境变量Docker配置详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！