SSR模式下nuxt.config.ts无法读取带NUXT_前缀的.env环境变量

问题场景 #

在Nuxt3的SSR模式下，nuxt.config.ts中的runtimeConfig配置无法读取.env文件中带有NUXT_前缀的自定义环境变量。相关配置如下：

nuxt.config.ts 中的 runtimeConfig 配置

runtimeConfig: {
    strapiAdminToken: '',
    public: {
        strapiBaseUri: '',
        stripe: {
            publishableKey: '',
        },
    }
}

.env 文件示例

NUXT_PUBLIC_STRAPI_BASE_URI=blablabla
NUXT_STRAPI_ADMIN_TOKEN=blababla

Docker Compose 运行配置

nuxt-app:
    container_name: nuxt-app
    image: ${CI_REGISTRY_IMAGE}/nuxt-app:latest
    restart: unless-stopped
    volumes:
      - ./.env/:/src/.env
    ports:
      - "3000:3000"
    networks:
      - Strapi

排查与解决步骤 #

1. 修正Docker挂载路径错误 #

你的Docker Compose中挂载的是./.env/:/src/.env，左侧的.env/是目录路径而非文件路径。如果本地是单个.env文件，需将挂载配置改为：

volumes:
  - ./.env:/src/.env

（多余的斜杠会导致容器内/src/.env变成目录，Nuxt无法读取其中的变量）

2. 验证容器内.env文件状态 #

进入容器检查文件是否正确挂载：

docker exec -it nuxt-app cat /src/.env

如果输出为空或提示文件不存在，说明挂载路径错误，需调整volumes配置。

3. 确认Nuxt环境变量匹配规则 #

Nuxt3的环境变量加载逻辑需严格遵循：

• 服务器端变量：NUXT_前缀 + runtimeConfig中的键名（如NUXT_STRAPI_ADMIN_TOKEN对应runtimeConfig.strapiAdminToken）
• 客户端公开变量：NUXT_PUBLIC_前缀 + runtimeConfig.public中的键名（如NUXT_PUBLIC_STRAPI_BASE_URI对应runtimeConfig.public.strapiBaseUri）
  你的变量命名符合规则，重点确保文件能被正确读取。

4. 本地环境验证 #

脱离Docker在本地运行项目，检查变量是否能正常读取：

npm run dev

如果本地正常，说明问题出在Docker配置；如果本地也异常，检查：

• .env文件是否在项目根目录
• 变量名是否存在拼写错误（大小写、下划线）
• 无需额外安装@nuxtjs/dotenv，Nuxt3默认内置dotenv支持

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