在 nuxt 3 应用开发中，针对不同部署环境（如开发、测试、生产）使用不同的 api url 是常见的需求。本文将详细介绍如何利用 nuxt 3 的 `runtimeconfig` 功能，结合 `process.env.node_env` 环境变量，优雅地实现基于环境的 api 地址配置，并提供在组件或页面中安全访问这些配置的实践方法，确保应用在不同环境中能够正确地与后端服务交互。
引言
在现代 Web 应用开发中，前端应用经常需要与不同的后端服务进行交互。这些后端服务的地址（API URL）通常会根据应用所处的环境（例如，开发环境、测试环境、生产环境）而有所不同。为了避免手动修改代码并在部署时引发错误，配置一个灵活且环境感知的 API URL 机制至关重要。Nuxt 3 提供了强大的 runtimeConfig 功能，能够优雅地解决这一问题。
Nuxt 3 runtimeConfig 概述
Nuxt 3 的 runtimeConfig 是一个用于在应用程序运行时暴露配置的强大功能。它允许您定义可以在服务器端和客户端访问的配置变量。这对于那些在构建时未知，或者需要根据部署环境动态调整的配置（如 API 密钥、数据库连接字符串或本文讨论的 API URL）非常有用。
runtimeConfig 主要分为两部分：
- runtimeConfig.public: 这部分配置会被暴露到客户端（浏览器），因此可以在客户端代码中直接访问。适合存放不敏感但需要在客户端使用的配置，例如 API 基础 URL。
- runtimeConfig (非 public 部分): 这部分配置仅在服务器端可用，不会暴露给客户端。适合存放敏感信息，如私有 API 密钥或数据库凭证。
本文将主要关注 runtimeConfig.public，因为它适用于在客户端发起请求时使用不同的 API URL。
配置基于环境的 API URL
要实现基于环境的 API URL 配置，我们需要在 nuxt.config.ts 文件中定义这些变量，并利用 process.env.NODE_ENV 来判断当前环境。
步骤一：在 nuxt.config.ts 中定义环境相关的 API URL
在您的 nuxt.config.ts 文件中，您可以像以下示例一样设置 runtimeConfig.public：
// nuxt.config.ts
// 判断当前是否为生产环境
const isProdEnv = process.env.NODE_ENV === 'production';
// 定义不同环境的 API 端点
const testEndpoint = 'https://api.example.com/test'; // 测试环境 API
const prodEndpoint = 'https://api.example.com/prod'; // 生产环境 API
// 根据环境选择合适的 API 端点
const servicesEndpoint = isProdEnv ? prodEndpoint : testEndpoint;
export default defineNuxtConfig({
runtimeConfig: {
public: {
// 将 API 基础 URL 暴露给客户端
apiBaseUrl: servicesEndpoint
}
},
// 其他 Nuxt 配置...
});代码解析：
- process.env.NODE_ENV: 这是一个标准的 Node.js 环境变量，通常在开发环境为 'development'，在生产环境为 'production'。Nuxt 3 会自动根据运行模式设置它。
- isProdEnv: 通过判断 NODE_ENV 是否为 'production' 来确定当前是否为生产环境。
- testEndpoint 和 prodEndpoint: 分别定义了测试环境和生产环境的 API URL。您可以根据实际需求定义更多环境（如 stagingEndpoint）。
- servicesEndpoint: 使用三元运算符根据 isProdEnv 的值动态选择 API URL。
- runtimeConfig.public.apiBaseUrl: 将最终确定的 servicesEndpoint 赋值给 apiBaseUrl，并将其放置在 public 对象中，使其可以在客户端访问。
步骤二：在应用中访问配置
一旦在 nuxt.config.ts 中配置了 runtimeConfig.public，您就可以在 Nuxt 3 应用的任何地方（包括组件、页面、插件、中间件等）使用 useRuntimeConfig() 组合式函数来访问这些配置。
// 例如，在某个组件或页面中API URL 示例
当前 API 基础 URL: {{ apiBaseUrl }}
代码解析：
- import { useRuntimeConfig } from '#app';: 导入 Nuxt 提供的 useRuntimeConfig 组合式函数。
- const runtimeConfig = useRuntimeConfig();: 调用该函数以获取整个 runtimeConfig 对象。
- const { apiBaseUrl } = runtimeConfig.public;: 通过 runtimeConfig.public 访问您在 nuxt.config.ts 中定义的 apiBaseUrl。
注意事项与最佳实践
-
环境变量的设置:
process.env.NODE_ENV 通常由 Nuxt 自动设置。当您运行 nuxt dev 时，它通常是 'development'；当您运行 nuxt build 后再启动服务时，它通常是 'production'。
-
如果您需要自定义其他环境变量（例如 DEPLOYMENT_ENV），可以在运行 Nuxt 命令时设置它们：
# 在 Linux/macOS DEPLOYMENT_ENV=staging nuxt build # 在 Windows (Command Prompt) set DEPLOYMENT_ENV=staging && nuxt build # 在 Windows (PowerShell) $env:DEPLOYMENT_ENV="staging"; nuxt build
然后在 nuxt.config.ts 中使用 process.env.DEPLOYMENT_ENV 进行判断。
敏感信息: 永远不要将敏感信息（如数据库密码、私有 API 密钥）放置在 runtimeConfig.public 中，因为这部分配置会被发送到客户端浏览器，容易被窃取。敏感信息应仅通过非 public 的 runtimeConfig 暴露给服务器端，或者直接通过服务器端环境变量管理。
-
类型安全: 结合 TypeScript，您可以为 runtimeConfig 定义类型，以获得更好的开发体验和类型检查。
// nuxt.config.ts export default defineNuxtConfig({ runtimeConfig: { public: { apiBaseUrl: '...', // ... 其他公共配置 }, // ... 非公共配置 } }) // 在您的应用代码中，useRuntimeConfig 会自动推断类型 const config = useRuntimeConfig() // config.public.apiBaseUrl 会有正确的字符串类型 模块化配置: 对于复杂的应用，您可以考虑将环境相关的配置抽象到单独的文件中，然后在 nuxt.config.ts 中导入。
总结
通过利用 Nuxt 3 的 runtimeConfig 和 process.env.NODE_ENV 环境变量，您可以轻松地实现基于不同部署环境的 API URL 配置。这种方法不仅提高了代码的可维护性和灵活性，还避免了在不同环境之间手动切换配置的繁琐和潜在错误。遵循本文提供的步骤和最佳实践，您的 Nuxt 3 应用将能够更健壮、更高效地管理其外部服务依赖。
