Nuxt 4 nuxt.config 配置详解：runtimeConfig 与 app.config 区别

本节目标：理解 nuxt.config.ts 的结构，认识常用的顶层配置字段，重点掌握 runtimeConfig 怎么安全地管理密钥和公开配置，以及它和 app.config 的区别。

Nuxt 遵循「约定优于配置」，大部分事不用配就能跑。但真正要定制行为时，所有开关都集中在项目根目录的 nuxt.config.ts 里。这一章把它拆开讲。

7-1

nuxt.config.ts 导出一个 defineNuxtConfig 函数，里面放一个配置对象。最精简的配置文件长这样：

export default defineNuxtConfig({
  // 这里写你的配置
})

defineNuxtConfig 是全局可用的，不需要你写 import 去引入它。它主要作用是：给你的配置对象提供类型提示——写错字段名或写错类型，IDE 会直接标红提醒你。

Tip

即便你不想用 TypeScript 写业务代码，也强烈建议把 nuxt.config 用 .ts 后缀。这样在配置里就能享受类型检查和自动补全，避免把 ssr 写成 sssr 这类手滑错误。

7-2

Nuxt 的配置项非常多，初学时先记住这几个最高频的：

devtools：是否开启 Nuxt 开发者工具面板。
ssr：是否开启服务端渲染。设 false 就变成纯客户端渲染（SPA）。
modules：要安装的 Nuxt 模块（比如 @nuxtjs/tailwindcss）。
css：全局生效的样式文件列表。
runtimeConfig：运行时配置（见下文）。
app：应用级配置，如 head（页面 <head> 默认内容）、baseURL 等。
nitro：服务端引擎相关配置（preset、路由规则等）。
routeRules：按路由定制渲染与缓存策略（混合渲染用，第 43 章细讲）。
srcDir：源码目录，Nuxt 4 默认就是 app。

一个更真实一点的例子：

export default defineNuxtConfig({
  compatibilityVersion: 4,
  devtools: { enabled: true },
  modules: ['@nuxtjs/tailwindcss'],
  css: ['~/assets/main.css'],
  ssr: true,
})

7-3

Nuxt 配置支持「按环境覆盖」。比如你想让生产环境启用 ISR 缓存、开发环境不启用，可以这样写：

export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {
    // 开发环境留空
  },
  $env: {
    staging: {
      // 名为 staging 的环境才生效
    },
  },
})

运行时用 --envName 指定环境：nuxt build --envName staging。这个机制背后是 c12 这个配置库，日常用得不多，知道存在即可。

7-4

runtimeConfig 用来存放「运行时才能确定、尤其不该写死在前端代码里」的值，典型就是 API 密钥、数据库连接串。

它分两部分：私密值只服务端可用，public 里的会暴露给浏览器端。

export default defineNuxtConfig({
  runtimeConfig: {
    // 私密密钥，仅服务端可见
    apiSecret: '123',
    // public 里的值，服务端和浏览器端都能拿到
    public: {
      apiBase: '/api',
    },
  },
})

这些值的巧妙之处在于：它们可以用环境变量覆盖，不用改代码。比如建一个 .env 文件：

# 这会覆盖上面的 apiSecret
NUXT_API_SECRET=api_secret_token

注意环境变量名的规律：配置里的 apiSecret 对应 NUXT_API_SECRET，即前缀 NUXT_ 加全大写字段名。

在代码里通过 useRuntimeConfig() 读取：

<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
// 服务端能拿到 runtimeConfig.apiSecret
// 两端都能拿到 runtimeConfig.public.apiBase
</script>

Warning

千万别把私密值直接写进组件模板或前端代码——runtimeConfig 里非 public 的部分只在服务端存在，一旦你把它传给浏览器端（比如塞进 public），密钥就泄露了。需要前端用的配置，才放进 public。

7-5

除了 runtimeConfig，Nuxt 还有个 app.config.ts，也能暴露配置给应用。它放在 app/ 目录下：

export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: { primary: '#ff0000' },
  },
})

在代码里用 useAppConfig() 读取。它和 runtimeConfig 的区别是：app.config 在构建时就确定了，不能用环境变量覆盖；runtimeConfig 可以在部署后用环境变量改。

选哪个？简单记：

敏感或部署后才确定的（密钥、接口地址）→ 用 runtimeConfig。
构建期就定好的公开配置（站点标题、主题色）→ 用 app.config。

特性	runtimeConfig	app.config
客户端可用	仅 `public` 部分	是
可用环境变量覆盖	✅	❌
典型用途	密钥、运行时地址	主题、标题

7-6

Nuxt 把很多原本散落的配置文件「收编」了：Nitro、PostCSS、Vite、webpack 的配置都不再用独立的 nitro.config.ts、vite.config.ts 文件，而是写在 nuxt.config.ts 的对应字段里（如 nitro、vite、postcss）。这样配置有唯一来源，不容易冲突。

例如给 Vite 传 Vue 插件选项：

export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
  },
})

7-7

nuxt.config.ts 不是改了就立刻全量重启。Nuxt 对配置改动做了分级处理：

大部分字段（如 css、modules、ssr）改动后，Nuxt 会重启开发服务器并重新生成类型，终端能看到重启日志，等它跑完刷新页面即可。
极少数字段改了需要你手动停掉 dev 重跑才彻底生效（比如涉及 Nitro 预设、构建目标的部分）。
重新生成类型这一步意味着：你加了一个模块或改了 runtimeConfig，IDE 的类型提示往往要等重启完成才更新——别急着怀疑自己写错。

Tip

改配置后页面「没反应」，先看终端有没有在重启。如果卡住，按 Ctrl+C 重跑 npm run dev 永远是最稳的。

7-8

app 这个顶层字段管的是「应用层面」的事，几个高频子项：

app.head：给所有页面统一加 <head> 内容，比如网站标题、图标、字体链接。
app.baseURL：应用部署在子路径（如 https://example.com/blog/）时，用它告诉 Nuxt 根路径在哪，否则资源会 404。
app.layouts：是否启用目录式布局（默认开）。

举例，给整站加一个默认标题和 favicon：

export default defineNuxtConfig({
  app: {
    head: {
      title: '我的 Nuxt 站点',
      link: [{ rel: 'icon', href: '/favicon.ico' }],
    },
  },
})

app.head 里写的标题是兜底值，单个页面还能用 useHead 覆盖它，做成每页不同标题。

Note

app.baseURL 和部署强相关：本地开发多是根路径（/）不用管；一旦上线到子目录，漏配它是最常见的「本地好好的、上线全 404」元凶之一。

7-9

nuxt.config.ts 是 Nuxt 的总控制台，用 defineNuxtConfig 包裹配置对象。高频字段有 modules、css、ssr、runtimeConfig 等。敏感配置放 runtimeConfig（用环境变量覆盖），公开构建期配置放 app.config。下一章我们讲一个影响深远的配置：渲染模式。

7-9 配置文件的调试技巧

修改 nuxt.config.ts 后，开发服务器会自动重启。如果你发现改了配置但没生效，先确认文件是否保存成功，再看终端有没有报错日志。有时候一个拼写错误会导致整个配置文件解析失败，服务器无法启动。

调试配置值的一个实用方法是在 defineNuxtConfig 里临时加 console.log。比如在 setup 钩子里打印当前的运行时配置，帮你确认值是否符合预期。另外，nuxi dev --dotenv .env.local 可以指定加载哪个环境文件，方便你在不同环境配置间切换测试。

当项目配置越来越复杂时，建议把不同关注点的配置用注释分段，或者提取成独立的变量和函数。保持 nuxt.config.ts 的可读性，对团队长期维护非常重要。

7-10 模块化配置的拆分技巧

当 nuxt.config.ts 里的配置项越来越多时，把所有内容塞进一个文件会变得难以维护。一个实用的技巧是把相关配置提取成独立的对象或函数。比如把 SEO 相关的配置封装成一个 seoConfig() 函数，把安全相关的头信息封装成 securityHeaders() 函数，然后在 defineNuxtConfig 里调用它们。

这种方式让配置文件保持清晰的结构，每个关注点都有自己的”领地”。团队成员修改某个方面的配置时，不需要在整个大文件里翻找。配合 TypeScript 的类型提示，修改配置时的准确性和效率都会显著提升。