在 Nuxt 3 项目里，API URL 这类环境相关配置如果直接硬编码到代码里，会导致每次切换环境都要重新构建。Nuxt 3 设计了 runtimeConfig 体系，把配置分为公开和私有两部分，让同一套构建产物能够适应不同部署环境。
为什么不能直接写死 API 地址
很多团队在初期会把请求基地址写成类似 const API_BASE = 'https://api.ippipp.com' 的常量。这种做法在单一环境运转良好，但一旦需要并行运行测试环境和生产环境，就会出问题。前端代码经过打包后，地址已经被固化进 JavaScript 文件，修改意味着重新编译和部署。
更合理的做法是把地址延迟到运行时决定。Nuxt 3 的 Nitro 服务器引擎支持在启动阶段读取系统环境变量，并把它注入到应用上下文中。这样我们在本地开发、Docker 容器或者云函数里，只要改变环境变量，就能控制 API 指向，而不碰业务代码。
使用 runtimeConfig 声明配置
Nuxt 3 的核心配置文件是 nuxt.config.ts。在其中我们可以通过 runtimeConfig 字段定义两类值：public 下面的属性会暴露给浏览器端，server 下面的属性仅在服务端可用，不会泄露给客户端。
下面是一段基础配置示例，我们定义了公开的 apiBase 和服务端专用的内部令牌。注意 public 中的值如果以 NUXT_PUBLIC_ 开头的环境变量覆盖，server 中的值则用普通变量名注入。
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// 服务端私有配置，客户端拿不到
internalToken: '',
// 公开配置，客户端可读取
public: {
apiBase: 'http://127.0.0.1:3000/api'
}
}
})
对应的 .env 文件可以这样写，前缀规则让 Nuxt 自动映射。NUXT_PUBLIC_API_BASE 会覆盖 public.apiBase，而 INTERNAL_TOKEN 会填入 runtimeConfig.internalToken。
# .env 文件，不要提交到仓库 NUXT_PUBLIC_API_BASE=https://api.ipipp.com/api INTERNAL_TOKEN=secret_value_123
在代码中读取配置
客户端组件里应使用 useRuntimeConfig 的 public 属性。该函数由 Nuxt 自动注入，返回的对象在浏览器和服务器两侧都能安全调用，但私有字段在服务端之外为空。
// 页面或组件内
const config = useRuntimeConfig()
const base = config.public.apiBase
async function loadUser() {
const res = await fetch(base + '/user')
return res.json()
}
如果是服务端接口或 Nitro 路由，直接用 useRuntimeConfig 不加 public 即可拿到全部字段，包括内部令牌。这样我们可以安全地转发请求而不暴露密钥。
// server/api/proxy.ts
export default defineEventHandler(async (event) => {
const config = useRuntimeConfig()
const resp = await fetch(config.public.apiBase + '/data', {
headers: { Authorization: 'Bearer ' + config.internalToken }
})
return resp.json()
})
多环境部署实践
在 CI/CD 流程中，我们通常不会把 .env 放进代码库，而是在部署平台设置环境变量。例如测试环境填入 NUXT_PUBLIC_API_BASE=https://test.ipipp.com/api，生产环境填正式域名。构建只需一次，运行时各自读取。
| 环境 | 变量名 | 示例值 |
|---|---|---|
| 本地开发 | NUXT_PUBLIC_API_BASE | http://127.0.0.1:3000/api |
| 测试环境 | NUXT_PUBLIC_API_BASE | https://test.ipipp.com/api |
| 生产环境 | NUXT_PUBLIC_API_BASE | https://api.ipipp.com/api |
这种表格方式能清晰展现变量如何随环境变化。需要注意，public 配置在构建时若未提供环境变量，会采用 nuxt.config.ts 里的默认值，因此本地没有 .env 也能启动。
另外，Nitro 支持通过 NITRO_PRESET 切换部署目标，如 node-server、vercel 等。不同预设对环境变量的读取方式一致，我们不需要为云平台改写配置逻辑，只需在对应后台配置变量即可。
常见误区与排查
一个典型错误是在客户端试图读取私有配置，例如 config.internalToken 在前端永远为空字符串。若需要调用带鉴权的接口，必须把请求放在 server 目录下的路由中代理，而不是浏览器直接发请求。
另一个坑是混淆构建时和运行时。如果用了 process.env.XXX 直接写在客户端代码，它会在打包时被静态替换，无法随环境变化。坚持使用 useRuntimeConfig 才能确保运行时生效。
总结：通过 runtimeConfig 与 .env 配合，Nuxt 3 能优雅地隔离环境差异，让 API URL 等配置动态可调，既安全又便于运维。
Nuxt3environment_variableruntime_config修改时间：2026-08-08 22:06:28