Nuxt项目教程：从@nuxtjs/dotenv迁移到运行时配置

何举烈Damon

于 2025-06-25 09:10:40 发布

阅读量313

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.csdn.net/gitblog_00270/article/details/148890011

Nuxt项目教程：从@nuxtjs/dotenv迁移到运行时配置

website-v2 Nuxt 2 Documentation Website 项目地址: https://gitcode.com/gh_mirrors/we/website-v2

在Nuxt.js项目开发中，环境变量的管理是一个重要环节。本文将详细介绍如何从传统的@nuxtjs/dotenv模块迁移到Nuxt 2.13+版本引入的更安全、更高效的运行时配置系统。

环境变量的基本概念

前端应用经常需要与API和第三方服务集成，这些集成通常需要配置数据，而这些数据通常由环境变量提供。需要注意的是，浏览器环境对所有访问者都是可见的，因此敏感信息不应直接暴露给前端。

常见误区解析

许多开发者误以为将敏感密钥放在.env文件中就能保证安全，但实际上：

.env文件虽然可以通过.gitignore避免上传到版本控制系统
但.env文件本身并未加密，只是将敏感数据隐藏起来
错误使用仍可能导致密钥泄露到客户端代码中

Webpack的作用

Nuxt作为同构(universal)应用框架，需要同时在服务端和客户端运行JavaScript代码：

Node.js使用require模块系统
浏览器对模块的支持不完全
Webpack负责将模块代码转换为浏览器可理解的格式
同时处理HTML、CSS和图片等资源

环境变量的工作原理

Node.js在运行时自动将环境变量加载到process.env对象中。Webpack在构建时会将这些引用替换为实际值。这意味着：

构建时读取环境变量值
值会被固化到Webpack打包结果中
修改环境变量后需要重新构建应用

Nuxt运行时配置介绍

Nuxt 2.13+引入了更安全的运行时配置系统，具有以下优势：

内置dotenv支持
更好的安全性
更快的开发体验

配置方式是在nuxt.config.js中添加两个新选项：

export default {
  publicRuntimeConfig: {},  // 公共配置，会暴露给前端
  privateRuntimeConfig: {}  // 私有配置，仅服务端可用
}

重要说明

privateRuntimeConfig在服务端会覆盖publicRuntimeConfig中的同名属性
客户端只能访问publicRuntimeConfig中的配置
静态站点生成(SSG)仍需重新生成以获取配置变更

迁移步骤详解

从@nuxtjs/dotenv迁移

卸载@nuxtjs/dotenv模块
从nuxt.config.js的modules部分移除该模块
将.env文件中的变量转移到运行时配置

示例迁移：

// 迁移前.env
BASE_URL=https://v2.nuxt.com
API_SECRET=1234

// 迁移后nuxt.config.js
export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL
  },
  privateRuntimeConfig: {
    apiSecret: process.env.API_SECRET
  }
}

简化配置技巧

可以使用默认值简化配置：

export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL || 'https://v2.nuxt.com'
  }
}

或者根据环境切换配置：

export default {
  publicRuntimeConfig: {
    baseURL: process.env.NODE_ENV === 'production' 
      ? 'https://v2.nuxt.com' 
      : 'https://dev.nuxtjs.org'
  }
}

从env属性迁移

如果原本使用env属性：

export default {
  env: {
    BASE_URL: 'https://v2.nuxt.com',
    API_SECRET: '1234'
  }
}

迁移后应为：

export default {
  publicRuntimeConfig: {
    baseURL: 'https://v2.nuxt.com'
  },
  privateRuntimeConfig: {
    apiSecret: process.env.API_SECRET
  }
}

配置值的使用方法

在代码中可以通过以下方式访问配置：

在页面、store、组件和插件中：

// 通过this.$config
asyncData({ $config: { baseURL } }) {
  const posts = await fetch(`${baseURL}/posts`)
}

在模板中直接使用：

<template>
  <p>Our URL: {{ $config.baseURL }}</p>
</template>

最佳实践建议

应该避免的

❌ 不要在Git中提交敏感值或密钥
❌ 不要在nuxt.config.js或.env中存储密钥，除非已添加到.gitignore

高级特性

变量扩展

环境变量扩展只在键已存在时生效：

// .env
API_SECRET=1234

// nuxt.config.js
export default {
  privateRuntimeConfig: {
    API_SECRET: '' // 会被.env中的值覆盖
  }
}

变量插值

支持环境变量的嵌套引用：

// .env
BASE_URL=/api
PUBLIC_URL=https://v2.nuxt.com

// nuxt.config.js
export default {
  privateRuntimeConfig: {
    baseURL: '${PUBLIC_URL}${BASE_URL}' // 结果为https://v2.nuxt.com/api
  }
}