配置系统
Nuxt 自带合理默认值，大多数项目只改几项配置。nuxt.config.ts 是唯一的真相源：模块、环境覆盖、runtimeConfig、Vite/Nitro 透传、Vue 开关全写在这里。
nuxt.config.ts
export default defineNuxtConfig({
devtools: { enabled: true },
modules: ['@pinia/nuxt', '@nuxtjs/tailwindcss'],
css: ['~/assets/css/main.css'],
})
defineNuxtConfig 全局可用（不需要 import），并且有完整的 TypeScript 补全。
按环境覆盖
Nuxt 会在合并前优先读取 $development、$production、$env.*：
export default defineNuxtConfig({
$production: {
routeRules: {
'/**': { isr: true },
},
},
$development: {
devtools: { enabled: true },
},
$env: {
staging: { app: { baseURL: '/staging/' } },
},
})
构建时通过 nuxt build --envName staging 指定环境。背后由 c12 实现。
runtimeConfig 与 app.config 的区别
两者都能暴露配置值，但解决的问题不同：
| 关注点 | runtimeConfig |
app.config |
|---|---|---|
| 定义位置 | nuxt.config.ts |
app.config.ts |
| 支持环境变量覆盖 | 是（NUXT_*） |
否 |
| 客户端可访问 | 只有 public 下的键 |
完整打包 |
| 支持非基础 JS 类型 | 否 | 是 |
| 响应式 | 是 | 是 |
| 适合用来放 | 密钥、URL、Token | 主题、站点元信息、开关 |
runtimeConfig
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: '', // 仅服务端
public: {
apiBase: '/api', // 暴露给客户端
},
},
})
通过环境变量覆盖：
NUXT_API_SECRET=prod_secret
NUXT_PUBLIC_API_BASE=https://api.example.com
使用 composable 读取：
<script setup lang="ts">
const { apiSecret, public: { apiBase } } = useRuntimeConfig()
</script>
在客户端，
apiSecret会是undefined。
app.config
// app/app.config.ts
export default defineAppConfig({
title: 'Hello Nuxt',
theme: { dark: true, colors: { primary: '#3b82f6' } },
})
<script setup lang="ts">
const appConfig = useAppConfig()
</script>
app.config 支持 HMR —— 改主题会立即生效。
TypeScript
Nuxt 会自动生成 .nuxt/tsconfig.json，项目的 tsconfig.json 继承它，无需手动配置。
需要自定义时：
export default defineNuxtConfig({
typescript: {
strict: true,
typeCheck: true, // 构建时跑 vue-tsc
},
})
给 Vite / Nitro / PostCSS 传选项
Nuxt 不会 读取外部的 vite.config.ts / nitro.config.ts，都要通过 Nuxt 的 key 透传：
export default defineNuxtConfig({
vite: {
plugins: [/* … */],
},
nitro: {
preset: 'node-server',
compressPublicAssets: true,
},
postcss: {
plugins: {
'postcss-nested': {},
},
},
})
Vue 相关开关
export default defineNuxtConfig({
vue: {
propsDestructure: true, // 实验特性
},
})
也可以直接通过 vite.vue 给 @vitejs/plugin-vue 传参。
应用级 head
要应用到所有页面的静态标签放在 app.head：
export default defineNuxtConfig({
app: {
head: {
titleTemplate: '%s · Nuxt 小册',
htmlAttrs: { lang: 'zh-CN' },
link: [{ rel: 'icon', href: '/favicon.ico' }],
},
},
})
页面级、动态标签用 useHead() —— 详见 SEO 那章。
怎么选？
- 项目里的静态开关？ →
app.config - 密钥或环境相关？ →
runtimeConfig - 构建期转换？ →
nuxt.config（vite/nitrokey） - 按环境切换？ →
$development/$production/$env
一个文件，四个旋钮，足够把项目跑起来。
