本文详解如何在 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）模式下环境管理的标准实践。
