本教程详细介绍了如何在 nuxt 3 应用中根据不同的部署环境（如开发、测试、生产）动态配置和使用不同的 api 端点。通过利用 nuxt 3 的 `runtimeconfig` 和 `process.env.node_env`，开发者可以轻松实现环境敏感的配置管理，确保应用在不同阶段调用正确的后端服务，从而提高开发效率和部署的灵活性。
在现代 Web 应用开发中，根据不同的部署环境（例如开发、测试、生产）使用不同的后端 API 地址是常见的需求。Nuxt 3 提供了一套强大且灵活的配置系统来处理这类场景，特别是通过其 runtimeConfig 选项。本文将指导您如何在 Nuxt 3 项目中实现基于环境的 API URL 配置。
理解 Nuxt 3 的运行时配置 (Runtime Config)
Nuxt 3 引入了 runtimeConfig，它允许您在应用程序运行时（包括客户端和服务器端）访问配置变量。runtimeConfig 分为两部分：
- runtimeConfig.public: 这些变量会在客户端和服务器端都暴露，适合存放那些不敏感但需要全局访问的配置，如 API 基础 URL。
- runtimeConfig (非 public): 这些变量仅在服务器端可用，适合存放敏感信息，如私有 API 密钥。
基于环境配置 API URL
要根据环境设置不同的 API URL，我们将利用 process.env.NODE_ENV 变量来判断当前运行环境，并将其与 runtimeConfig.public 结合使用。
1. 配置 nuxt.config.ts
在您的 nuxt.config.ts 文件中，您可以像以下示例一样定义环境相关的 API URL：
// nuxt.config.ts
// 判断当前是否为生产环境
const isProdEnv = process.env.NODE_ENV === 'production'
// 定义不同环境的 API 端点
const testEndpoint = 'https://api.example.com/test'
const prodEndpoint = 'https://api.example.com/prod'
// 根据环境选择对应的 API 端点
const servicesEndpoint = isProdEnv ? prodEndpoint : testEndpoint
export default defineNuxtConfig({
runtimeConfig: {
// public 部分的配置会在客户端和服务器端都暴露
public: {
apiBaseUrl: servicesEndpoint // 将选择的 API 端点赋值给 apiBaseUrl
}
},
// 其他 Nuxt 配置项...
})代码解析：
- process.env.NODE_ENV: 这是一个标准的 Node.js 环境变量，在开发模式下通常为 'development'，在生产构建时通常为 'production'。Nuxt 3 会自动设置此变量。
- defineNuxtConfig: Nuxt 3 的配置定义函数。
- runtimeConfig.public.apiBaseUrl: 我们在这里定义了一个名为 apiBaseUrl 的公共运行时配置变量，它的值会根据 isProdEnv 的判断结果动态设置。
2. 在应用中访问配置
配置完成后，您可以在 Nuxt 3 应用的任何组件、页面、插件或组合式函数中通过 useRuntimeConfig() 组合式函数来访问这些变量。
// 例如，在某个组件或组合式函数中
import { useRuntimeConfig } from '#app' // 或直接从 'nuxt' 导入
export default {
setup() {
// 解构获取公共运行时配置
const { public: { apiBaseUrl } } = useRuntimeConfig()
// 现在您可以使用 apiBaseUrl 来构建您的 API 请求
console.log('当前 API 基础 URL:', apiBaseUrl)
// 示例：发起一个 API 请求
async function fetchData() {
try {
const response = await fetch(`${apiBaseUrl}/data`)
const data = await response.json()
console.log('获取到的数据:', data)
} catch (error) {
console.error('API 请求失败:', error)
}
}
fetchData()
return {
// ...
}
}
}代码解析：
- useRuntimeConfig(): Nuxt 3 提供的一个组合式函数，用于访问应用程序的运行时配置。
- const { public: { apiBaseUrl } } = useRuntimeConfig(): 通过解构赋值，您可以直接获取到在 nuxt.config.ts 中定义的 apiBaseUrl。
注意事项与最佳实践
-
环境变量管理 (.env 文件): 虽然直接在 nuxt.config.ts 中硬编码 URL 适用于简单场景，但更推荐使用 .env 文件来管理环境变量。
- 在项目根目录创建 .env 文件（例如 .env.development, .env.production）。
- 在 .env.development 中：NUXT_PUBLIC_API_BASE_URL=https://api.example.com/test
- 在 .env.production 中：NUXT_PUBLIC_API_BASE_URL=https://api.example.com/prod
- 在 nuxt.config.ts 中：
export default defineNuxtConfig({ runtimeConfig: { public: { apiBaseUrl: process.env.NUXT_PUBLIC_API_BASE_URL // 直接从环境变量获取 } }, }) - Nuxt 3 会自动加载 .env 文件中的 NUXT_ 或 NUXT_PUBLIC_ 开头的变量。NUXT_PUBLIC_ 前缀的变量会自动暴露到客户端。
安全性: 请记住，runtimeConfig.public 中的所有变量都会被打包到客户端 JavaScript 中，因此绝不能在此处存放任何敏感信息，如数据库密码、私有 API 密钥等。敏感信息应仅通过 runtimeConfig（非 public 部分）在服务器端使用。
-
类型安全: 为了更好的开发体验和类型安全，您可以在 nuxt.config.ts 中为 runtimeConfig 定义类型：
// nuxt.config.ts export default defineNuxtConfig({ runtimeConfig: { public: { apiBaseUrl: 'https://default.example.com' as string, // 明确类型 } } })或者在 tsconfig.json 中配置 typeRoots 和 types，并创建 runtime.d.ts 文件。
总结
通过利用 Nuxt 3 的 runtimeConfig 和 process.env.NODE_ENV，您可以轻松地实现环境敏感的 API URL 配置。这种方法不仅清晰、易于维护，而且符合 Nuxt 3 的设计哲学，确保您的应用程序在不同环境中能够正确、安全地运行。结合 .env 文件管理环境变量，将进一步提升配置的灵活性和可维护性。
