在 Nuxt 3 项目里，API 地址如果硬编码在页面或组件内，每次切换开发、测试、生产环境都要手动改代码重新打包，既容易遗漏也破坏持续交付流程。Nuxt 3 的设计思路是把环境相关的变量抽离到配置层，通过统一的入口在服务端和客户端分别注入，从而保证构建产物可以跨环境复用。理解这套机制，是做好动态 API URL 管理的第一步。
runtimeConfig 的核心原理与基础用法
Nuxt 3 的 runtimeConfig 是定义在 nuxt.config.ts 中的特殊配置对象，它在构建阶段被序列化，并在应用启动时注入到 Nitro 服务端引擎以及客户端 bundle 中。与普通的编译时变量不同，runtimeConfig 允许部分配置在运行时通过环境变量覆盖，而不需要重新构建。例如，我们可以在配置中声明一个 apiBase 字段，专门用于存放后端接口的根地址。
在 nuxt.config.ts 里，runtimeConfig 分为公开和私有两部分。写在顶层的是服务端可用的私有配置，而放在 public 下的字段会被打包到客户端，因此绝对不能把密钥放进去。针对 API URL 这种本来就允许浏览器访问的地址，通常将其放在 public 中，这样前端组件才能直接读取。下面是一段基础配置示例：
export default defineNuxtConfig({
runtimeConfig: {
// 服务端私有配置，客户端拿不到
internalToken: 'server-only-secret',
// 公开配置，会暴露给浏览器
public: {
apiBase: process.env.NUXT_PUBLIC_API_BASE || 'http://127.0.0.1:3001'
}
}
})
上述代码中，process.env.NUXT_PUBLIC_API_BASE 是构建或运行时的环境变量。如果启动时设置了该变量，就会覆盖默认值；否则使用本地地址。要注意，以 NUXT_PUBLIC_ 开头的环境变量会被 Nuxt 自动映射到 runtimeConfig.public 对应字段，这是一种约定优于配置的设计，可以减少手动声明的工作量。
通过 .env 文件实现多环境动态切换
实际开发中，我们不会直接去服务器上敲环境变量，而是用 .env 文件做环境隔离。Nuxt 3 默认支持项目根目录下的 .env、.env.development、.env.production 等文件，它们在对应模式下自动加载。把不同环境的 API URL 写进各自的 .env 文件，就能做到切换模式即切换地址，无需改动源码。
举例来说，本地开发的 .env 可以写 NUXT_PUBLIC_API_BASE=http://127.0.0.1:3001，而生产环境的 .env.production 写 NUXT_PUBLIC_API_BASE=https://api.ipipp.com。执行 npm run build 后再用 NODE_ENV=production 启动，Nitro 会读取生产文件中的值注入客户端。这种方式比在 CI 脚本里拼字符串更安全，也方便运维审查。示例如下：
# .env.development NUXT_PUBLIC_API_BASE=http://127.0.0.1:3001 # .env.production NUXT_PUBLIC_API_BASE=https://api.ipipp.com
需要提醒的是，.env 文件通常包含环境差异信息，不应提交到公开仓库。如果某些地址必须随代码走，可以在 nuxt.config.ts 里写死兜底值，再用 .env 覆盖。此外，Vercel、Netlify 等平台支持在控制台配置环境变量，效果和本地 .env 一致，但优先级可能更高，部署前要确认没有冲突。
在组件与服务端分别读取 API URL 的正确姿势
很多初学者分不清客户端和服务端读取配置的区别。在客户端代码中，应通过 useRuntimeConfig() 的 public 属性获取地址；而在服务端（如 Nitro 接口或 useFetch 的服务器端渲染阶段），直接用 useRuntimeConfig() 顶层属性即可拿到完整配置。错误地在前端访问私有字段会得到 undefined，导致请求发到 undefined/api 这样的非法地址。
下面展示一个在页面中拼接 API 路径的写法：
<script setup lang="ts">
const config = useRuntimeConfig()
const base = config.public.apiBase
const { data } = await useFetch('/user/list', {
baseURL: base
})
</script>
在服务端 API 路由里，如果想代理转发，可以这样写：
// server/api/proxy.ts
export default defineEventHandler(async (event) => {
const config = useRuntimeConfig()
// 服务端可同时拿到 public 和私有配置
const target = config.public.apiBase + '/internal/data'
return await $fetch(target)
})
从安全与维护角度看，把所有环境相关的 URL 收敛到 runtimeConfig 之后，组件中不应再出现任何带主机名的字符串。如果团队使用 Docker，也可以在容器启动命令中加入 -e NUXT_PUBLIC_API_BASE=https://api.ipipp.com 来覆盖镜像内默认值，实现同一镜像多环境部署。结合上述实践，动态 API URL 管理就不再是散落在各处的硬编码，而是可审计、可切换的标准化配置。
Nuxt3API_URLenvironment_config修改时间：2026-08-17 06:28:29