Nuxt 4 开发教程

Appearance

配置对比 ​

Nuxt 提供了多种配置方式，理解它们各自的职责和边界，才能把配置放在正确的位置。放错位置的配置不仅难以维护，还可能造成安全隐患。

全局配置体系一览 ​

text
Nuxt 项目的所有配置项
│
├── nuxt.config.ts         → Nuxt 行为配置（模块、路由规则、构建选项）
│   └── runtimeConfig      → 运行时环境变量（API 密钥、数据库地址等）
│
├── app/app.config.ts      → 应用 UI 配置（主题色、功能开关等）
│
├── .env                   → 环境变量文件（覆盖 runtimeConfig 默认值）
│
├── .nuxtrc                → 简化配置（个人偏好、快速设置）
│
├── .nuxtignore            → 忽略构建文件
│
└── tsconfig.json          → TypeScript 配置（通常只 extends）

App Config vs Runtime Config ​

这是最常见也最容易混淆的对比：

特性app.configruntimeConfig
定义位置app/app.config.tsnuxt.config.ts
确定时机构建时运行时
环境变量覆盖❌✅
私有配置❌ 全部公开✅ 服务端独有
响应式✅❌
可修改✅ updateAppConfig❌ 只读
Payload 传递✅✅（public 部分）
修改后需要重新构建重启服务即可
安全性不应放敏感信息私有配置不会泄露到客户端

核心区别：构建时 vs 运行时 ​

text
app.config（构建时确定）
┌───────────────────────────────────────────┐
│ nuxt build 时，配置被打包进 JS 文件          │
│ 改了 app.config.ts → 必须重新构建           │
│ 优点：客户端可以直接使用，无需请求服务器       │
└───────────────────────────────────────────┘

runtimeConfig（运行时确定）
┌───────────────────────────────────────────┐
│ 服务启动时读取环境变量，填充默认值           │
│ 改了 .env → 重启服务即可                   │
│ 优点：不同环境不同值，无需重新构建           │
└───────────────────────────────────────────┘

为什么这个区别很重要？

想象你有一个 SaaS 产品部署在 10 台服务器上。如果 API 地址放在 app.config 中，改一次地址就要重新构建 + 10 台服务器全部重新部署。放在 runtimeConfig 中，只需更新 .env 并重启服务。

何时用 App Config ​

  • 主题色、字体大小等 UI 配置
  • 功能开关（feature flags）
  • 需要在运行时动态修改的配置
  • 前端布局、样式相关配置
  • 不涉及安全的配置
ts
// app/app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: '#00DC82',
    darkMode: false,
    borderRadius: '8px',
  },
  features: {
    enableChat: true,
    enableNotifications: true,
  },
})
ts
const appConfig = useAppConfig()
appConfig.theme.primaryColor  // '#00DC82'

运行时修改 app.config ​

app.config 是响应式的，可以在运行时修改（比如用户切换深色模式）：

ts
const appConfig = useAppConfig()

// 修改配置（所有使用 useAppConfig 的组件都会响应式更新）
updateAppConfig({
  theme: {
    darkMode: true,
  },
})

updateAppConfig 做了什么？

它深度合并新配置到现有配置，触发所有依赖该配置的组件重新渲染。这个修改只影响当前用户，不影响其他用户或服务器。

INFO

️ updateAppConfig 修改的是客户端状态 刷新页面后会恢复为 app.config.ts 中定义的默认值。如果需要持久化，配合 useCookie 或 localStorage

何时用 Runtime Config ​

  • API 密钥、数据库连接字符串
  • 第三方服务密钥
  • 需要根据环境变化的配置
  • 服务端私有配置
ts
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 服务端私有（客户端看不到）
    apiSecret: '',
    dbUrl: '',
    jwtSecret: '',

    // 公共（客户端和服务端都可见）
    public: {
      apiBase: '/api',
      appName: 'MyApp',
    },
  },
})
ts
// 服务端代码
const config = useRuntimeConfig()
config.apiSecret      // ✅ 有值
config.public.apiBase // ✅ 有值

// 客户端代码
const config = useRuntimeConfig()
config.apiSecret      // ❌ undefined（安全！）
config.public.apiBase // ✅ 有值

私有配置为什么客户端拿不到？

Nuxt 在构建时就知道哪些配置是私有的。对于私有配置，Nuxt 不会将其包含在发送到浏览器的 JavaScript 中。即使用户打开 DevTools 也看不到。

nuxt.config.ts 中的其他配置项 ​

除了 runtimeConfig，nuxt.config.ts 还控制 Nuxt 的核心行为：

配置项作用何时修改
ssrSSR/CSR 模式切换后台管理页面不需要 SEO 时
modules安装的模块添加新功能时
routeRules路由级渲染策略不同页面需要不同缓存策略
css全局样式文件引入全局 CSS
viteVite 构建配置需要自定义构建行为
nitro服务端引擎配置修改部署预设、存储配置
app.head全局 Head 标签设置默认标题、meta
compatibilityDate行为兼容日期项目创建时设置，一般不改

这些配置修改后都需要重启开发服务器

因为它们影响的是构建行为，不是运行时行为。

共同使用示例 ​

ts
// nuxt.config.ts
export default defineNuxtConfig({
  // 运行时配置：环境相关、敏感信息
  runtimeConfig: {
    apiSecret: process.env.API_SECRET,
    dbUrl: process.env.DATABASE_URL,
    public: {
      apiBase: process.env.API_BASE || '/api',
    },
  },
})
ts
// app/app.config.ts
export default defineAppConfig({
  // 应用配置：UI 相关、不敏感
  theme: {
    primaryColor: '#00DC82',
    darkMode: false,
  },
  features: {
    enableChat: true,
  },
})
ts
// 在组件中同时使用
const config = useRuntimeConfig()
const appConfig = useAppConfig()

// 环境相关 → runtimeConfig
const apiBase = config.public.apiBase

// UI 相关 → appConfig
const theme = appConfig.theme.primaryColor

决策流程 ​

text
需要存储什么？
│
├── 环境相关的密钥/URL → runtimeConfig
│   ├── 仅服务端 → runtimeConfig（非 public）
│   │   如：数据库密码、JWT 密钥、第三方 API Key
│   └── 客户端也需要 → runtimeConfig.public
│       如：API 基础地址、应用名称
│
└── UI/主题/功能开关 → app.config
    ├── 运行时可修改 → app.config + updateAppConfig
    │   如：深色模式切换、字体大小调整
    └── 构建时确定 → app.config
        如：主题色、默认布局参数

常见错误 ​

❌ 把 API 密钥放在 app.config 中 ​

ts
// ❌ 危险！app.config 是公开的，客户端能看到
export default defineAppConfig({
  apiKey: 'sk-xxx',  // 任何人打开 DevTools 都能看到！
})

// ✅ 正确：放在 runtimeConfig 的私有部分
export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: '',  // 通过 NUXT_API_KEY 环境变量注入
  },
})

❌ 把主题色放在 runtimeConfig 中 ​

ts
// ❌ 不推荐：runtimeConfig 不是响应式的，客户端修改不了
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      primaryColor: '#00DC82',
    },
  },
})

// ✅ 正确：app.config 是响应式的，运行时可修改
export default defineAppConfig({
  theme: {
    primaryColor: '#00DC82',
  },
})

❌ 混淆环境变量的前缀 ​

bash
# ❌ 错误：app.config 不支持环境变量覆盖
NUXT_PUBLIC_THEME_COLOR=red  # 这个对 app.config 无效！

# ✅ 正确：runtimeConfig 的环境变量
NUXT_PUBLIC_API_BASE=https://api.example.com  # 这个有效

❌ 在 app.config 中使用运行时 API ​

ts
// ❌ 错误：app.config 在构建时执行，process.env 不一定可用
export default defineAppConfig({
  apiBase: process.env.API_BASE,  // 构建时可能为 undefined
})

// ✅ 正确：runtimeConfig 才使用环境变量
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.API_BASE || '/api',
    },
  },
})

知识脉络 ​

text
高级进阶 → 你在这里：配置对比
              │
              ├─→ 回顾：项目配置（01-快速入门/05-项目配置）
              ├─→ 回顾：核心文件（02-目录结构/05-核心文件）
              └─→ 下一步：实验性特性

基于 Nuxt 4 官方文档整理编写

MIT License