nuxt运行时配置

“运行时配置”是 Nuxt 的核心特性之一，它允许你在不重新构建代码的情况下，通过环境变量动态改变应用的行为（比如在开发环境用本地数据库，在生产环境用云端 API）。

如何定义运行时配置

在nuxt.config.ts中，使用runtimeConfig属性进行配置。它分为两个核心区域：

export default defineNuxtConfig({
  runtimeConfig: {
    // 1. 私密配置：仅在服务端（Node.js）可用
    apiSecret: '12345', 

    // 2. 公开配置：服务端和客户端（浏览器）均可用
    public: {
      apiBase: 'https://www.fengfengzhidao.com',
      siteName: '枫枫知道'
    }
  }
})

核心区别对照表：

区域	访问权限	典型用途
runtimeConfig** (顶层)**	仅服务端	数据库密码、支付密钥、私有 Token
public** (子项)**	服务端 + 客户端	API 根地址、公开的 CDN 路径、SEO 信息

如何获取变量

使用 Nuxt 提供的 useRuntimeConfig() 组合式函数。

<script setup>
const config = useRuntimeConfig()

// 客户端只能看到 public 里的内容
console.log(config.public.apiBase) 

// 只有在 server/api 或 SSR 阶段（服务端）才能看到 apiSecret
if (import.meta.server) {
  console.log(config.apiSecret)
}
</script>

• 只读性：useRuntimeConfig()返回的对象是**只读 (Read-only)**的。你不能在代码里动态修改config.public.apiBase = 'xxx'，它只能通过环境变量在启动时改变。
• **不要混淆：**绝对不要把数据库密码、私钥放在public 节点下。一旦放进去，Nuxt 会将其序列化并发送到浏览器端，任何人通过开发者工具都能看到。

虽然在server/目录下（如 API Routes）也可以使用useRuntimeConfig()

// server/api/test.ts
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event) // 传入 event 更加稳健
  return { secret: config.apiSecret }
})

.env文件的自动加载

在开发环境下（nuxt dev），你不需要手动在终端输入命令。Nuxt 会自动读取根目录下的.env 文件。

• **命名约定：**必须以NUXT_ 开头。
• **优先级：**环境变量 >.env文件 >nuxt.config.ts 中的默认值。

需要在配置文件里面登记这些变量名称，在env文件里面名字遵循大写下划线方式，使用遵循小驼峰方式

NUXT_API_SECRET=super_secret_key
NUXT_PUBLIC_API_BASE=https://staging-api.example.com

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', 
    public: {
      apiBase: ''
    }
  }
})

根据环境读取不同.env文件

Nuxt 的底层引擎 Nitro 支持通过命令行指定读取哪个.env文件。你可以根据环境创建不同的文件，如.env.staging或.env.production。

{
  "scripts": {
    "dev": "nuxi dev", 
    "dev:staging": "nuxi dev --dotenv .env.staging",
    "build:staging": "nuxi build --dotenv .env.staging",
    "preview:staging": "nuxi preview --dotenv .env.staging"
  }
}

环境变量覆盖

Nuxt 允许你使用以NUXT_开头的环境变量来自动覆盖nuxt.config.ts 中的值。

映射规则：

• 私密配置：NUXT_API_SECRET对应apiSecret
• 公开配置：NUXT_PUBLIC_API_BASE对应public.apiBase（层级用下划线隔开）

# 在 Linux 或 Docker 启动时
NUXT_PUBLIC_API_BASE=https://prod-api.com 
# windows的cmd设置环境变量，只针对当前终端生效
set NUXT_PUBLIC_API_BASE=https://prod-api.com 
node .output/server/index.mjs

**优势：**你不需要为了修改一个 API 地址而重新执行npm run build，极大地提高了 CI/CD 的效率。

变量覆盖优先级

当同一个配置项在多个地方出现时，Nuxt 会按照以下顺序进行覆盖（数字越大，优先级越高）：

1. **默认值：**在nuxt.config.ts的runtimeConfig 中定义的初始值。
2. .env 文件：项目根目录下的.env文件（在dev 模式或手动加载时有效）。
3. **系统环境变量：**直接在 Linux 终端通过export 定义，或在 Docker 启动脚本中传入的变量。
4. **命令行注入：**启动命令前的临时赋值（如NUXT_API_KEY=xxx node ...）。