Nuxt Configuration 完全参考：nuxt.config.ts 全部配置项解析与工程实践

2026-09-07 11:52:58作者：咎竹峻Karen

nuxt.config.ts 是 Nuxt（当前仓库为 full-stack Vue 框架 Nuxt 的主仓库）中唯一一个集中声明应用行为的配置文件。无论是路径别名、构建器选择、目录结构定制、运行时配置，还是与 Nitro、Vite、webpack、TypeScript 的集成，都由这个文件统一驱动。本文以仓库文档 docs/4.api/6.nuxt-config.md 为主体骨架，结合 packages/schema/src/config/common.ts 等类型与解析器源码，逐一解析其核心配置项的类型、默认值与实战写法，帮助你做到"按需查阅、即拿即用"。

配置项的底层定义与默认值解析逻辑集中在 packages/schema/src/types/config.ts（NuxtConfig 接口）与 packages/schema/src/config 下按主题拆分的 resolver 文件（如 common.ts、app.ts、vite.ts、webpack.ts），并在 packages/schema/src/index.ts 中统一导出 NuxtConfigSchema。defineNuxtConfig 帮助函数为配置文件提供完整的类型提示与校验。

1. 认识 nuxt.config.ts：入口、目录与解析流程

1.1 rootDir / srcDir / workspaceDir：三个"根目录"的职责划分

配置中有多个以 Dir 结尾的路径项，理解它们的语义关系是配置一切的前提：

rootDir：应用根目录。默认值为 /<rootDir>（即当前工作目录）。运行 nuxt ./my-app/ 时会被自动覆盖为 ./my-app/ 的绝对路径，因此通常无需手动配置。
srcDir：源码目录。Nuxt 4 默认值为 app（若不存在 app/ 目录则回退到 rootDir）；Nuxt 3 且 compatibilityMode: 3 时默认为 .。若配置相对路径，则相对 rootDir 解析。
workspaceDir：工作区目录，主要用于 monorepo 场景。Nuxt 会尝试自动探测，也可在此手动覆盖，默认值 /<workspaceDir>。
serverDir：服务端目录（Nitro 路由、中间件与插件存放处），默认 /<rootDir>/server，相对路径基于 rootDir。
buildDir：构建产物目录，默认 /<rootDir>/.nuxt。由于 .nuxt 是隐藏目录（以点开头），部分工具链不识别时，可通过该选项改名。
analyzeDir：nuxt analyze 生成分析文件的存放目录，默认 /<rootDir>/.nuxt/analyze，相对路径同样基于 rootDir。
modulesDir：模块解析目录数组，默认 ["/<rootDir>/node_modules"]。yarn workspace 风格 monorepo 场景下可能需要配置，如 modulesDir: ['../../node_modules']。

从源码看，这些路径解析器定义在 packages/schema/src/config/common.ts：srcDir 的 resolver 会先探测 app 目录是否存在，再根据 app.vue、dir.assets 等关键文件/目录决定是否回退到根目录；buildDir 的 resolver 则将相对值 resolve(rootDir, '.nuxt')；analyzeDir 默认 resolve(buildDir, 'analyze')。

1.2 从源码看 `srcDir: 'app/'` 期望的目录结构

当配置 srcDir 时，Nuxt 期望如下结构（示例见文档）：

-| app/
---| assets/
---| components/
---| composables/
---| layouts/
---| middleware/
---| pages/
---| plugins/
---| utils/
---| app.config.ts
---| app.vue
---| error.vue
-| server/
-| shared/
-| public/
-| modules/
-| layers/
-| nuxt.config.ts
-| package.json

export default defineNuxtConfig({
  srcDir: 'app/',
})

1.3 dir：整体定制目录结构

dir 对象允许微调 Nuxt 约定的默认目录，官方建议除非确有需要否则保持默认：

键	类型	默认值	说明
`dir.app`	`string`	`"app"`	应用目录
`dir.assets`	`string`	`"app/assets"`	资源目录（构建时别名 `~assets`）
`dir.layouts`	`string`	`"app/layouts"`	布局目录，文件自动注册为布局
`dir.middleware`	`string`	`"app/middleware"`	中间件目录，文件自动注册
`dir.modules`	`string`	`"modules"`	本地模块目录，文件自动注册为模块
`dir.pages`	`string`	`"app/pages"`	页面目录，用于自动生成路由
`dir.plugins`	`string`	`"app/plugins"`	插件目录，文件自动注册
`dir.public`	`string`	`"public"`	静态文件目录，直接经 Nuxt 服务端暴露，`generate` 时拷贝进 `dist`
`dir.shared`	`string`	`"shared"`	app 与 server 共享的目录

2. alias：为自定义目录定义别名，提升开发体验（DX）

alias 用来为 JS 与 CSS 中的自定义目录添加访问别名。

类型：object
默认值：

{
  "~": "/<rootDir>/app",
  "@": "/<rootDir>/app",
  "~~": "/<rootDir>",
  "@@": "/<rootDir>",
  "#shared": "/<rootDir>/shared",
  "#server": "/<rootDir>/server",
  "assets": "/<rootDir>/app/assets",
  "public": "/<rootDir>/public",
  "#build": "/<rootDir>/.nuxt",
  "#internal/nuxt/paths": "/<rootDir>/.nuxt/paths.mjs"
}

:::callout 注意：在 webpack 上下文中（图片资源、CSS——但不含 JavaScript）必须用 ~ 前缀访问别名。 :::

:::callout 这些别名会自动加入生成的 TypeScript 配置（.nuxt/tsconfig.app.json、.nuxt/tsconfig.server.json 等），从而获得完整类型支持与路径自动补全。若需要扩展生成配置，请在此处或 typescript.tsConfig 中追加。 :::

示例（添加图片、样式、数据目录别名，并在组件模板、script、style 中使用）：

import { fileURLToPath } from 'node:url'

export default defineNuxtConfig({
  alias: {
    'images': fileURLToPath(new URL('./assets/images', import.meta.url)),
    'style': fileURLToPath(new URL('./assets/style', import.meta.url)),
    'data': fileURLToPath(new URL('./assets/other/data', import.meta.url)),
  },
})

<template>
  <img src="~images/main-bg.jpg">
</template>

<script>
import data from 'data/test.json'
</script>

<style>
// Uncomment the below
//@import '~style/variables.scss';
//@import '~style/utils.scss';
//@import '~style/base.scss';
body {
  background-image: url('~images/main-bg.jpg');
}
</style>

从源码看，alias 的 resolver（packages/schema/src/config/common.ts）会基于已解析的 srcDir、rootDir、buildDir、dir.shared、serverDir 拼出默认别名对象，再与用户传入的 val 合并，因此用户别名可覆盖内置别名。

3. app：Nuxt 应用级配置

app 对象管理应用挂载、资源路径、<head> 默认值与路由过渡行为。

3.1 baseURL、buildAssetsDir 与 cdnURL

app.baseURL：Nuxt 应用的基路径。类型 string，默认 "/"。

export default defineNuxtConfig({
  app: {
    baseURL: '/prefix/',
  },
})

也可运行时通过环境变量 NUXT_APP_BASE_URL 设置：

NUXT_APP_BASE_URL=/prefix/ node .output/server/index.mjs

:::note 由于 Nitro 限制，nuxt.config.ts 中不能直接使用相对路径（如 ./）。静态托管需要相对资源路径时，用下面两种方案之一：

方案一（构建时环境变量）：

NUXT_APP_BASE_URL=./ npm run generate

方案二（Nitro 运行时配置）：

export default defineNuxtConfig({
  nitro: {
    runtimeConfig: {
      app: {
        baseURL: './',
      },
    },
  },
})

:::

app.buildAssetsDir：构建产物资源所在文件夹名，相对 baseURL（若设置了 cdnURL 则相对它）。构建期决定、不建议运行时修改。类型 string，默认 "/_nuxt/"。
app.cdnURL：生产环境下用于提供 public 文件夹资源的绝对 URL。类型 string，默认 ""。

export default defineNuxtConfig({
  app: {
    cdnURL: 'https://mycdn.org/',
  },
})

运行时同样可用环境变量覆盖：NUXT_APP_CDN_URL=https://mycdn.org/ node .output/server/index.mjs。

3.2 head：全站 `<head>` 默认配置

类型 object，默认包含移动端 viewport 与 utf-8 字符集：

{
  "meta": [
    { "name": "viewport", "content": "width=device-width, initial-scale=1" },
    { "charset": "utf-8" }
  ],
  "link": [],
  "style": [],
  "script": [],
  "noscript": []
}

示例（配置 meta、外部脚本、样式表、内联 style 与 noscript 提示）：

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
      // <meta name="viewport" content="width=device-width, initial-scale=1">
        { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      ],
      script: [
      // <script src="https://myawesome-lib.js"></script>
        { src: 'https://awesome-lib.js' },
      ],
      link: [
      // <link rel="stylesheet" href="https://myawesome-lib.css">
        { rel: 'stylesheet', href: 'https://awesome-lib.css' },
      ],
      // please note that this is an area that is likely to change
      style: [
      // <style>:root { color: red }</style>
        { textContent: ':root { color: red }' },
      ],
      noscript: [
      // <noscript>JavaScript is required</noscript>
        { textContent: 'JavaScript is required' },
      ],
    },
  },
})

3.3 keepalive、pageTransition、layoutTransition 与 viewTransition

app.keepalive：页面间 KeepAlive 配置的默认值。类型 boolean，默认 false。可通过单页的 definePageMeta 覆盖；仅允许 JSON 可序列化值。底层对应 Vue 的 KeepAlive 组件。
app.layoutTransition：布局切换过渡默认值。类型 boolean | TransitionProps，默认 false。同样可被 definePageMeta 覆盖，仅允许 JSON 可序列化值，对应 Vue 的 Transition 组件。
app.pageTransition：页面过渡默认值。类型 boolean | TransitionProps，默认 false。覆盖规则同上。
app.viewTransition：View Transitions 默认值。类型 boolean，默认 false。仅在开启实验性 View Transitions 支持（参见 transitions 指南）时生效，可被单个页面的 definePageMeta 覆盖。

3.4 根元素、SPA loader 与 Teleport 元素定制

Nuxt 在 HTML 中会渲染一个根挂载元素、一个 SPA loading 占位元素，并把 Teleport 内容渲染到独立容器。这些元素的 id、tag 与属性均可定制：

配置项	类型	默认值	说明
`app.rootId`	`string`	`"__nuxt"`	根元素 id
`app.rootTag`	`string`	`"div"`	根元素标签
`app.rootAttrs`	`object`	`{"id":"__nuxt"}`	根元素附加属性
`app.spaLoaderTag`	`string`	`"div"`	SPA 加载元素标签
`app.spaLoaderAttrs`	`object`	`{"id":"__nuxt-loader"}`	SPA 加载元素属性（含子项 `id`，默认 `"__nuxt-loader"`）
`app.teleportId`	`string`	`"teleports"`	Teleport 容器 id
`app.teleportTag`	`string`	`"div"`	Teleport 容器标签
`app.teleportAttrs`	`object`	`{"id":"teleports"}`	Teleport 容器属性

例如想要多应用同页共存的场景，可把根 id 改掉：

export default defineNuxtConfig({
  app: { rootId: 'my-app' },
})

4. 构建体系：builder、build、buildId 与 sourcemap

4.1 builder：选择 Vue 应用的打包器

Nuxt 对客户端部分支持多种 builder，默认使用 Vite，可切换到 webpack、Rspack 或自定义 builder。

类型：'vite' | 'webpack' | 'rspack' | string | { bundle: (nuxt: Nuxt) => Promise<void> }
默认值："@nuxt/vite-builder"

export default defineNuxtConfig({
  // default - uses @nuxt/vite-builder
  // builder: 'vite',

  // uses @nuxt/webpack-builder
  // builder: 'webpack',

  // uses @nuxt/rspack-builder
  builder: 'rspack',
})

若选用 webpack 或 rspack，必须显式安装 @nuxt/webpack-builder 或 @nuxt/rspack-builder 到项目（对应仓库中 packages/webpack、packages/rspack 两个独立包）。也可传入含 bundle 函数的自定义 builder 对象：

export default defineNuxtConfig({
  builder: {
    async bundle (nuxt) {
      const entry = await resolvePath(resolve(nuxt.options.appDir, 'entry'))

      // Build client and server bundles
      await buildClient(nuxt, entry)
      if (nuxt.options.ssr) {
        await buildServer(nuxt, entry)
      }

      // ... it's a bit more complicated than that, of course!
    },
  },
})

作为独立包发布的自定义 builder 只需默认导出一个 bundle 函数，然后在配置里写包名即可：

export default defineNuxtConfig({
  builder: 'my-custom-builder',
})

4.2 server.builder：选择服务端构建方式

类型：string | { bundle: (nuxt: Nuxt) => Promise<void> }
默认值："@nuxt/nitro-server"

Nuxt 默认使用 @nuxt/nitro-server 提供独立 Nitro 集成，该架构也允许把 Nitro 作为 Vite 插件（借助 Vite Environment API）运行。"nitro" 与 "vite" 分别是 @nuxt/nitro-server 与 @nuxt/vite-server 的简写。后者为实验实现：仅用 Vite 构建客户端、不内置服务端，因此在 ssr: false 时产出静态 SPA；开启 SSR 时仍构建 server 环境，但运行职责交给自带 target 的 Vite 插件或自定义 server，且服务端路由、routeRules、预渲染均不可用，依赖服务端的模块也无法工作。

:::callout{type="warning"} 该选项面向内部使用，API 尚未定型，依赖当前实现前请先提 issue。 :::

4.3 build.*：共享构建配置

build.analyze（顶层亦有 analyze 语义）——启用打包体积可视化分析。设为 true 即可，也可传对象：webpack 走 webpack-bundle-analyzer 选项，vite 走 rollup-plugin-visualizer 选项。默认值：

{
  "template": "treemap",
  "projectRoot": "/<rootDir>",
  "filename": "/<rootDir>/.nuxt/analyze/{name}.html"
}

export default defineNuxtConfig({
  analyze: {
    analyzerMode: 'static',
  },
})

build.templates：自定义构建期生成的模板文件。官方建议改用 @nuxt/kit 的 addTemplate。

export default defineNuxtConfig({
  build: {
    templates: [
      {
        src: '~~/modules/support/plugin.js', // `src` can be absolute or relative
        dst: 'support.js', // `dst` is relative to project `.nuxt` dir
      },
    ],
  },
})

build.transpile：需要 Babel 转译的依赖列表。数组项可以是包名、函数、匹配依赖文件名的 string/regex。函数会收到 { isDev, isServer, isClient, isModern, isLegacy } 并返回条件结果：

export default defineNuxtConfig({
  build: {
    transpile: [({ isLegacy }) => isLegacy && 'ky'],
  },
})

buildId：与构建匹配的唯一标识，可包含项目当前状态的哈希。类型 string。其解析器（见 packages/schema/src/config/common.ts）在开发模式返回 'dev'、测试模式返回 'test'，否则生成随机 UUID——文档示例中的默认 UUID "4a2e2d30-..." 仅是某次构建的样例值。

4.4 sourcemap：服务端/客户端 sourcemap 策略

类型：object；若给单个 boolean，则对 client/server 同时生效。还支持 'hidden'。
默认值：

{
  "server": true,
  "client": false
}

取值语义：true 生成 sourcemap 并在产物中保留 source 引用；false 完全不生成；'hidden' 生成 sourcemap 但不写入产物引用。

5. 目录探测与忽略规则：ignore / ignorePrefix / ignoreOptions / extensions

ignore：比 ignorePrefix 更灵活的 glob 忽略数组。默认值：

[
  "**/*.stories.{js,cts,mts,ts,jsx,tsx}",
  "**/*.{spec,test}.{js,cts,mts,ts,jsx,tsx}",
  "**/*.d.{cts,mts,ts}",
  "**/*.d.vue.{cts,mts,ts}",
  "**/.{pnpm-store,vercel,netlify,output,git,cache,data}",
  "**/*.sock",
  ".nuxt/analyze",
  ".nuxt",
  "**/-*.*"
]

默认即忽略 Storybook 文件、spec/test 文件、类型声明文件、常见 CI/平台目录、.nuxt 等，并配合 **/-*.* 兜底 ignorePrefix 语义。

ignoreOptions：直接透传给底层 node-ignore 的选项。

export default defineNuxtConfig({
  ignoreOptions: {
    ignorecase: false,
  },
})

ignorePrefix：app/pages/、app/layouts/、app/middleware/ 与 public/ 中文件名以该前缀开头的文件在构建时被忽略（防止被处理或对外提供）。类型 string，默认 "-"（即 -foo.vue 这类文件不会参与处理）。Nuxt 本身的忽略实现可参见 packages/kit/src/ignore.ts。
extensions：Nuxt resolver 要解析的扩展名数组。默认：

[".js", ".jsx", ".mjs", ".ts", ".tsx", ".vue"]

源码中（packages/schema/src/config/common.ts）实现为：在默认 JS 扩展名（常量 DEFAULT_JS_FILE_EXTENSIONS）基础上始终附加 .vue，再把用户传入的新扩展名追加到尾部。

6. pages、components、plugins 与 auto-imports

6.1 pages

是否启用 Nuxt 的 vue-router 集成。不提供值时，若源码目录中存在 app/pages/ 则自动启用。也可以提供 glob 模式或模式数组以只扫描特定文件：

export default defineNuxtConfig({
  pages: {
    pattern: ['**/*/*.vue', '!**/*.spec.*'],
  },
})

6.2 components：组件自动注册

配置组件自动注册目录，其中任何组件都可免 import 地在页面、布局与其他组件中直接使用。相关目录约定详见 app/components 目录文档。

类型：object
默认值：

{
  "dirs": [
    { "path": "~/components/global", "global": true },
    "~/components"
  ]
}

6.3 css：全局 CSS 注入

定义要在每个页面全局引入的 CSS 文件/模块/库。Nuxt 按扩展名自动推断文件类型并选用对应预处理器（仍需自行安装所需 loader）。

export default defineNuxtConfig({
  css: [
  // Load a Node.js module directly (here it's a Sass file).
    'bulma',
    // CSS file in the project
    '~/assets/css/main.css',
    // SCSS file in the project
    '~/assets/css/main.scss',
  ],
})

6.4 plugins：显式声明应用插件

plugins 数组声明 Nuxt app 插件。每一项可以是字符串（绝对或相对路径；以 .client/.server 结尾会自动限定端侧），也可以是含 src 与 mode 的对象。

:::callout ~/plugins 目录中的插件会被自动注册，除非需要定制执行顺序否则不必在此列出；所有插件会按 src 路径去重。 :::

详见 app/plugins 目录文档。示例：

export default defineNuxtConfig({
  plugins: [
    '~/custom-plugins/foo.client.js', // only in client side
    '~/custom-plugins/bar.server.js', // only in server side
    '~/custom-plugins/baz.js', // both client & server
    { src: '~/custom-plugins/both-sides.js' },
    { src: '~/custom-plugins/client-only.js', mode: 'client' }, // only on client side
    { src: '~/custom-plugins/server-only.js', mode: 'server' }, // only on server side
  ],
})

6.5 imports：自动导入配置

详见 app/composables 目录文档。

imports.dirs：追加自动导入的自定义目录数组（不会覆盖默认的 ~/composables、~/utils）：

export default defineNuxtConfig({
  imports: {
  // Auto-import pinia stores defined in `~/stores`
    dirs: ['stores'],
  },
})

imports.global：类型 boolean，默认 false（是否全局注入而非按需 transform）。
imports.scan：类型 boolean，默认 true。是否扫描 app/composables/ 与 app/utils/ 目录以自动导入；Nuxt 或其他模块注册的导入（如来自 vue、nuxt 的）仍始终启用。

7. modules / extends / theme：分层与模块化扩展

7.1 modules

模块可扩展 Nuxt 核心功能。数组每项可以是字符串（包名，或指向文件的路径）、[module, options] 元组，或内联模块函数。Nuxt 先按 node 的 require 路径（node_modules）解析，若使用 ~~ 别名则相对项目 rootDir 解析。

:::callout 模块顺序执行，先后重要：先加载 nuxt.config.ts 中定义的模块，再执行 modules/ 目录中发现的模块（按字母顺序）。 :::

export default defineNuxtConfig({
  modules: [
  // Using package name
    '@nuxt/scripts',
    // Relative to your project rootDir
    '~~/custom-modules/awesome.js',
    // Providing options
    ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
    // Inline definition
    function () {},
  ],
})

7.2 extends / theme：多来源扩展

extends：从多个本地或远程源扩展项目。值为指向源目录/配置路径的字符串或字符串数组（相对当前配置），也支持 github:、gh:、gitlab:、bitbucket: 前缀的远程源。底层借助 c12 的 config layer 机制与 giget 拉取远程模板。
theme：从单个本地或远程源扩展（主题）。值为字符串，可指向本地源目录/配置路径，或通过 github:、gitlab:、bitbucket:、https:// 从远程 git 仓库扩展。

Nuxt 的 layer 系统与其配置解析方式可参见 layers 概念指南。

8. hooks 与 debug：事件监听与排障

8.1 hooks

hook 是 Nuxt 事件的监听器，通常由模块使用，也可直接写在 nuxt.config。内部命名采用冒号约定（如 build:done），为了方便，配置里可写成层级对象：

import fs from 'node:fs'
import path from 'node:path'

export default defineNuxtConfig({
  hooks: {
    build: {
      done (builder) {
        const extraFilePath = path.join(
          builder.nuxt.options.buildDir,
          'extra-file',
        )
        fs.writeFileSync(extraFilePath, 'Something extra')
      },
    },
  },
})

8.2 debug

debug: true 开启调试模式：目前会在服务端打印 hook 名称与耗时，在浏览器中记录 hook 参数。也可传对象精确开启某些调试项。

类型：boolean，默认 false。从 packages/schema/src/config/common.ts 的解析器可见，true 会被展开为 { templates, modules, watchers, hooks: { client, server }, nitro, router, hydration, perf } 全开的对象，并支持 NUXT_DEBUG_PERF 环境变量。

8.3 其余运行开关：dev / test / telemetry / ssr / logLevel

dev：是否开发模式。类型 boolean，默认 false（resolver 用 std-env 的 isDevelopment 推导），正常不需要手动设置。
test：应用是否处于单元测试状态。类型 boolean，默认 false（按 isTest 推导）。
telemetry：手动关闭 nuxt 遥测。
ssr：是否启用 HTML 渲染——服务端模式下动态渲染，或 generate 时静态生成；设为 false 则生成页面无内容。类型 boolean，默认 true。
logLevel：构建日志级别，默认 "info"；CI 或无 TTY 时默认 'silent'，并分别映射为 Vite 的 'silent' 与 webpack 的 'none'。

9. devServer 与 watch/watchers：开发期行为

9.1 devServer

devServer.port：监听端口。类型 number，默认 3000。
devServer.host：监听主机。
devServer.url：开发服务器完整 URL（默认 "http://localhost:3000"）。此值会被开发服务器用完整 URL 覆盖，仅供模块与内部使用，不建议直接设置。
devServer.https：是否启用 HTTPS。类型 boolean，默认 false。启用时可同时传 key/cert：

export default defineNuxtConfig({
  devServer: {
    https: {
      key: './server.key',
      cert: './server.crt',
    },
  },
})

devServer.cors：开发服务器 CORS 选项，含 origin 子项（类型 array，默认 [{}]）。
devServer.loadingTemplate：展示 loading 屏的模板函数。类型 function。

9.2 watch / watchers

watch：定义一组会在变更时重启 Nuxt 开发服务器的字符串或正则。字符串应为绝对路径或相对 srcDir（含各 layer 的 srcDir）；正则针对相对项目 srcDir（及各 layer srcDir）的路径匹配。类型 array。
watchers.chokidar：直接传给 chokidar 的选项，含 ignoreInitial（默认 true）与 ignorePermissionErrors（默认 true）。
watchers.rewatchOnRawEvents：收到这些事件类型时会让 watcher 重启的事件数组。
watchers.webpack：直接传给 webpack 的 watchOptions，含 aggregateTimeout（类型 number，默认 1000）。

10. runtimeConfig 与 nitro：运行时配置与覆盖

10.1 runtimeConfig

运行时配置把动态配置与环境变量传入 Nuxt app 上下文。对象值仅能在服务端通过 useRuntimeConfig 访问，主要保存不应暴露到前端的私有配置（如 API 密钥）；public 与 app 下的内容会同时暴露到前端。运行时，值会被同名环境变量自动替换。

类型：object
默认值：

{
  "public": {},
  "app": {
    "buildId": "4a2e2d30-418f-41df-8e58-ed5df06de7fd",
    "baseURL": "/",
    "buildAssetsDir": "/_nuxt/",
    "cdnURL": ""
  }
}

例如环境变量 NUXT_API_KEY=my-api-key NUXT_PUBLIC_BASE_URL=/foo/ 会覆盖下面示例中的两个值：

export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: '', // Default to an empty string, automatically set at runtime using process.env.NUXT_API_KEY
    public: {
      baseURL: '', // Exposed to the frontend as well.
    },
  },
})

10.2 nitro 与 routeRules

nitro：Nitro 配置（详见 nitro.config.ts 参考与 Nitro 官方文档）。其中：
- nitro.routeRules：类型 object。
- nitro.runtimeConfig：默认值含 public: {}、app: { buildId, baseURL, buildAssetsDir, cdnURL } 与 nitro: { envPrefix: 'NUXT_' }（即运行时环境变量默认以 NUXT_ 为前缀读取）。
routeRules：应用在匹配服务端路由上的全局路由规则，为实验性功能（API 可能变化），Nitro 侧定义见 Nitro route rules 文档。亦可通过 defineRouteRules 在页面级声明。
serverHandlers / devServerHandlers：前者为 Nitro 服务端 handler，后者为仅开发用的 Nitro handler。handler 支持 handler（文件路径）、route（遵循 rou3 约定）、method（HTTP 方法）、middleware（是否中间件）、lazy（是否懒加载导入）。

:::callout server/api、server/middleware 与 server/routes 中的文件会被 Nuxt 自动注册。 :::

详见 server 目录文档。

export default defineNuxtConfig({
  serverHandlers: [
    { route: '/path/foo/**:name', handler: '#server/foohandler.ts' },
  ],
})

11. 路由与过渡：router 与 view transition

11.1 router.options

透传给 vue-router 的附加选项。在 vue-router 原生选项之外，Nuxt 提供以下扩展：

:::callout 通过 Nuxt config 只能传 JSON 可序列化选项；需要更强控制时请使用 router.options.ts 文件（参见 custom-routing 配方）。 :::

router.options.hashMode：SPA 模式下启用 hash history。开启后路由 URL 前带 #，URL 永不发送到服务器且不支持 SSR。类型 boolean，默认 false。
router.options.scrollBehaviorType：定制 hash 链接的滚动行为。类型 string，默认 "auto"。

12. 样式体系：postcss / esbuild 与 Vue 编译

12.1 postcss

postcss.order：PostCSS 插件排序策略函数。类型 function。
postcss.plugins：PostCSS 插件选项。
- autoprefixer：为 CSS 规则添加厂商前缀的插件。
- cssnano：类型 object，选项见 cssnano 官方配置。

12.2 esbuild

Nuxt 内部的共享 esbuild 选项会透传给其他 builder（Vite 或 webpack）：

子项	类型	默认值
`esbuild.options.jsxFactory`	`string`	`"h"`
`esbuild.options.jsxFragment`	`string`	`"Fragment"`
`esbuild.options.target`	`string`	`"esnext"`
`esbuild.options.tsconfigRaw`	`object`	—

13. Vue 集成：vue、unhead 与编译选项

13.1 vue

vue.compilerOptions：构建期传给 Vue 编译器的选项（对应 Vue 应用配置 compilerOptions）。
vue.config：全局配置 Vue app。nuxt.config 中只允许传可序列化选项，其余需在 Nuxt plugin 里于运行时设置。
vue.propsDestructure：启用 defineProps 响应式解构。类型 boolean，默认 true。
vue.runtimeCompiler：是否把 Vue 编译器打入运行时包。类型 boolean，默认 false。开启后组件可在运行时编译模板（如字符串 template 选项或通过数据提供的模板）。

:::warning 运行时模板编译会把编译结果当作 JavaScript 执行。永远不要编译来自用户输入或不可信来源的模板，这等同于 eval，可能引发 XSS 或远程代码执行。 :::

vue.transformAssetUrls：模板中需要被解析为资源 URL 的属性映射，包含 image（默认 ["xlink:href","href"]）、img（["src"]）、source（["src"]）、use（["xlink:href","href"]）、video（["src","poster"]）等。

13.2 unhead

用于配置 unhead 模块的对象。

unhead.legacy：启用 unhead 兼容模式，会禁用 Capo.js 排序、启用支持 hid/vmid/children/body 的 DeprecationsPlugin、以及支持 promise 输入的 PromisesPlugin。类型 boolean，默认 false。

export default defineNuxtConfig({
  unhead: {
    legacy: true,
  },
})

unhead.renderSSRHeadOptions：传给 renderSSRHead 以定制输出。默认 { "omitLineBreaks": false }。

export default defineNuxtConfig({
  unhead: {
    renderSSRHeadOptions: {
      omitLineBreaks: true,
    },
  },
})

Nuxt 的头部管理 API 见 useHead。

14. TypeScript：类型生成与校验配置

Nuxt 的 TS 集成会生成 .nuxt/tsconfig.app.json、.nuxt/tsconfig.server.json、.nuxt/tsconfig.node.json、.nuxt/tsconfig.shared.json（及兼容性场景下的 .nuxt/tsconfig.json）。生成规则可参考 tsconfig.json 目录文档。

配置项	类型	默认值	说明
`typescript.strict`	`boolean`	`true`	启用 TS 严格检查
`typescript.typeCheck`	`boolean`	`false`	构建期类型检查；`true` 时开发期也检查，`'build'` 则仅构建期。需要安装 `typescript` 与 `vue-tsc` 依赖
`typescript.shim`	`boolean`	`false`	生成 `*.vue` shim。推荐使用官方 Vue 扩展生成准确类型；使用 ESLint 等无法理解 `.vue` 类型的库时可设为 `true`
`typescript.builder`	—	`null`	按 `builder` 选项推断（默认 vite）可引入对应 builder 类型；`false` 关闭环境类型自行处理；`'shared'` 适合模块作者以支持多种 builder
`typescript.tsConfig`	`object`	—	以共享选项扩展生成的 tsconfig。`compilerOptions` 对所有生成 tsconfig 生效；`include`/`exclude`/`vueCompilerOptions` 只作用于 app tsconfig。例外：DOM/Vue 相关选项（`lib`、`jsx`、`jsxImportSource`）只应用于 app tsconfig；`types`、`paths`、`noEmit` 由 Nuxt 按上下文管理，不能全局设置
`typescript.appTsConfig`	`object`	—	扩展 `.nuxt/tsconfig.app.json`（优先级高于 `tsConfig`）
`typescript.serverTsConfig`	`object`	—	扩展 `.nuxt/tsconfig.server.json`（优先级高于 `tsConfig`）
`typescript.nodeTsConfig`	`object`	—	扩展 `.nuxt/tsconfig.node.json`
`typescript.sharedTsConfig`	`object`	—	扩展 `.nuxt/tsconfig.shared.json`
`typescript.hoist`	`array`	见下	在 `compilerOptions.paths` 中为模块生成深层别名（不支持子路径），pnpm monorepo 且 `shamefully-hoist=false` 时可能需要

typescript.hoist 默认值：

[
  "nitro/types", "nitro/runtime-config", "nitro", "defu", "h3",
  "consola", "ofetch", "@unhead/vue", "@nuxt/devtools", "vue",
  "@vue/runtime-core", "@vue/compiler-sfc", "vue-router",
  "vue-router/auto-routes", "unplugin-vue-router/client",
  "@nuxt/schema", "nuxt"
]

另有 typescript.includeWorkspace（boolean，默认 false，将父 workspace 纳入项目，主要服务于主题/模块作者）。

15. Vite 配置：vite、$client 与 $server

vite 顶层选项会直接传给 Vite。顶层选项对 client/server 两个环境共享；$client、$server 分别提供仅作用于各自构建的配置并做合并。注意并非所有 Vite 选项都受 Nuxt 支持。

export default defineNuxtConfig({
  vite: {
    $client: {
      build: {
        rollupOptions: {
          output: {
            manualChunks: {
              analytics: ['analytics-package'],
            },
          },
        },
      },
    },
    $server: {
      build: {
        sourcemap: 'inline',
      },
    },
  },
})

关键默认值一览（文档完整列示）：

子项	类型	默认值
`vite.build.assetsDir`	`string`	`"_nuxt/"`
`vite.build.emptyOutDir`	`boolean`	`false`
`vite.cacheDir`	`string`	`"/<rootDir>/node_modules/.cache/vite"`
`vite.clearScreen`	`boolean`	`true`
`vite.mode`	`string`	`"production"`
`vite.root`	`string`	`"/<rootDir>"`
`vite.define`	`object`	`{ "__VUE_PROD_HYDRATION_MISMATCH_DETAILS__": false, "process.dev": false, "import.meta.dev": false, "process.test": false, "import.meta.test": false }`
`vite.esbuild`	`object`	`{ target: "esnext", jsxFactory: "h", jsxFragment: "Fragment", tsconfigRaw: {} }`
`vite.optimizeDeps.esbuildOptions`	`object`	同 `vite.esbuild`
`vite.optimizeDeps.exclude`	`array`	`["vue-demi"]`
`vite.resolve.extensions`	`array`	`[".mjs", ".js", ".ts", ".jsx", ".tsx", ".json", ".vue"]`
`vite.server.fs.allow`	`array`	`["/<rootDir>/.nuxt", "/<rootDir>/app", "/<rootDir>", "/<workspaceDir>"]`
`vite.vue.features.propsDestructure`	`boolean`	`true`
`vite.vue.isProduction`	`boolean`	`true`
`vite.vue.template.transformAssetUrls`	`object`	`{ video: ["src","poster"], source: ["src"], img: ["src"], image: ["xlink:href","href"], use: ["xlink:href","href"] }`
`vite.vueJsx`	`object`	`{ isCustomElement: {...} }`

Nuxt 的 Vite 集成实现位于 packages/vite/src（如 index.ts、vite.ts 负责装配与默认配置）。

16. webpack 配置详解（使用 webpack builder 时）

当 builder: 'webpack' 时启用以下配置（实现位于 packages/webpack/src）。本文按文档完整列示：

16.1 体积分析与产物命名

webpack.analyze：使用 webpack-bundle-analyzer 可视化 bundle。默认值同 build.analyze（template: "treemap"、projectRoot: "/<rootDir>"、filename: "/<rootDir>/.nuxt/analyze/{name}.html"）。示例：webpack: { analyze: { analyzerMode: 'static' } }。
webpack.filenames：定制产物文件名（app/chunk/css/font/img/video 均为函数类型）。注意：生产环境避免用非 hash 文件名，否则浏览器可能因缓存无法检测到首屏变更。

export default defineNuxtConfig({
  webpack: {
    filenames: {
      chunk: ({ isDev }) => (isDev ? '[name].js' : '[id].[contenthash].js'),
    },
  },
})

16.2 CSS 抽取与压缩

webpack.extractCSS：启用公共 CSS 抽取（基于 mini-css-extract-plugin），默认 true，把 CSS 拆成独立文件以利于 JS/CSS 分开缓存。文档建议不要把所有 CSS 合成单文件，多文件利于缓存与 preload 隔离、且按需下载可提升性能。若确需合成单文件，可配合 splitChunks：

export default defineNuxtConfig({
  webpack: {
    extractCSS: true,
    optimization: {
      splitChunks: {
        cacheGroups: {
          styles: {
            name: 'styles',
            test: /\.(css|vue)$/,
            chunks: 'all',
            enforce: true,
          },
        },
      },
    },
  },
})

webpack.optimizeCSS：OptimizeCSSAssetsPlugin 选项；extractCSS 开启时默认 true。类型 boolean，默认 false。
webpack.cssSourceMap：开发模式默认开启 CSS sourcemap；类型 boolean，默认 false。

16.3 optimization、插件与实验特性

webpack.optimization.minimize：设为 false 关闭全部压缩器（开发模式默认关闭）。类型 boolean，默认 true。
webpack.optimization.minimizer：自定义压缩器插件数组。
webpack.optimization.runtimeChunk：类型 string，默认 "single"。
webpack.optimization.splitChunks：含 automaticNameDelimiter（默认 "/"）、cacheGroups、chunks（默认 "all"）。
webpack.plugins：追加 webpack 插件数组。

import webpack from 'webpack'
import { version } from './package.json'

export default defineNuxtConfig({
  webpack: {
    plugins: [
      // ...
      new webpack.DefinePlugin({
        'process.VERSION': version,
      }),
    ],
  },
})

webpack.experiments：配置 webpack experiments 选项。
webpack.aggressiveCodeRemoval：硬替换 typeof process、typeof window、typeof document 以利于 tree-shake。类型 boolean，默认 false。
webpack.profile：在 webpackbar 中启用 profiler（常由 CLI --profile 触发）。类型 boolean，默认 false。
webpack.serverURLPolyfill：提供 URL/URLSearchParams 的 polyfill 库，默认 'url'。
webpack.warningIgnoreFilters：隐藏构建警告的过滤器数组。
webpack.friendlyErrors：设为 false 关闭 FriendlyErrorsWebpackPlugin 错误浮层。默认 true。
webpack.devMiddleware：见 webpack-dev-middleware 选项，含 stats（默认 "none"）。
webpack.hotMiddleware：见 webpack-hot-middleware 选项。
webpack.cssSourceMap 见上。

16.4 loaders 定制

Nuxt 内建 webpack loader 选项集中在 webpack.loaders：

loader	关键默认/子项
`css` / `cssModules`	`esModule: false`、`importLoaders: 0`、`url.filter`（函数）、cssModules 另有 `modules.localIdentName: "[local]_[hash:base64:5]"`
`esbuild`	`{ target: "esnext", jsxFactory: "h", jsxFragment: "Fragment", tsconfigRaw: {} }`
`file` / `fontUrl` / `imgUrl`	`esModule: false`、`limit: 1000`（转 base64 阈值，按文件类型分别配置）
`less` / `scss` / `stylus` / `vueStyle`	`sourceMap: false`
`sass`	`sassOptions.indentedSyntax: true`（sass 缩进语法）
`pugPlain`	见 pug 选项
`vue`	见 vue-loader；含 `compilerOptions`、`propsDestructure: true`、`transformAssetUrls`（video/source/img/image/use 的属性映射，默认值同前文 Vite/Vue 部分）
`postcss`	`postcssOptions.plugins` 默认 `{ autoprefixer: {}, cssnano: {} }`

17. optimization：构建期优化（async transforms / keyed composables / tree-shake）

17.1 asyncTransforms

optimization.asyncTransforms 选项直接透传给 unctx 的 transformer，用于在 await 之后保留 async 上下文：

asyncFunctions 默认：["defineNuxtPlugin", "defineNuxtRouteMiddleware"]
objectDefinitions 下的字段默认值：
- defineNuxtComponent: ["asyncData", "setup"]
- defineNuxtPlugin: ["setup"]
- definePageMeta: ["middleware", "validate"]

17.2 keyedComposables

需要注入 key 的函数列表。当实际传给函数的参数个数小于 argumentLength 时，会自动在末尾注入一个 magic string 作为 key；该 key 在 SSR 与客户端水合之间保持稳定，且基于函数在文件中的调用位置保证唯一。需自行处理这个多出来的 key。默认值：

[
  { "name": "callOnce", "argumentLength": 3, "source": "#app/composables/once" },
  { "name": "defineNuxtComponent", "argumentLength": 2, "source": "#app/composables/component" },
  { "name": "useState", "argumentLength": 2, "source": "#app/composables/state" },
  { "name": "useFetch", "argumentLength": 3, "source": "#app/composables/fetch" },
  { "name": "useAsyncData", "argumentLength": 3, "source": "#app/composables/asyncData" },
  { "name": "useLazyAsyncData", "argumentLength": 3, "source": "#app/composables/asyncData" },
  { "name": "useLazyFetch", "argumentLength": 3, "source": "#app/composables/fetch" }
]

关于 keyed function 的更多讲解见 recipes-basics：为函数加 key。对应运行时实现位于 packages/nuxt/src/app/composables（如 state.ts、asyncData.ts、fetch.ts）。

17.3 treeShake

按特定构建端 tree-shake 代码：

export default defineNuxtConfig({
  optimization: {
    treeShake: {
      composables: {
        client: { vue: ['onMounted'] },
        server: { vue: ['onServerPrefetch'] },
      },
    },
  },
})

默认配置会做对称裁剪——client 侧默认移除 vue 的 onRenderTracked/onRenderTriggered/onServerPrefetch 与 #app 的 definePayloadReducer/definePageMeta/onPrehydrate；server 侧默认移除 vue 的生命周期钩子（onMounted、onUpdated、onUnmounted、onBeforeMount、onBeforeUpdate、onBeforeUnmount、onRenderTracked、onRenderTriggered、onActivated、onDeactivated）与 #app 的 definePayloadReviver/definePageMeta。

18. SPA 静态加载与实验特性

18.1 spaLoadingTemplate

boolean 或 HTML 文件路径，文件内容会插入到所有 ssr: false 渲染的 HTML 页面中：

未设置：若某 layer 中存在 ~/spa-loading-template.html 则使用之；
false：不加载任何 SPA loading 指示器；
true：查找 ~/spa-loading-template.html，找不到则使用 Nuxt 默认图案。

可选 spinner 参考 SpinKit 或 SVG Spinners。默认值：null。

示例 ~/spa-loading-template.html（纯 CSS 转圈 loader）：

<div class="loader"></div>
<style>
.loader {
  display: block;
  position: fixed;
  z-index: 1031;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  width: 18px;
  height: 18px;
  box-sizing: border-box;
  border: solid 2px transparent;
  border-top-color: #000;
  border-left-color: #000;
  border-bottom-color: #efefef;
  border-right-color: #efefef;
  border-radius: 50%;
  -webkit-animation: loader 400ms linear infinite;
  animation: loader 400ms linear infinite;
}

@-webkit-keyframes loader {
  0% { -webkit-transform: translate(-50%, -50%) rotate(0deg); }
  100% { -webkit-transform: translate(-50%, -50%) rotate(360deg); }
}
@keyframes loader {
  0% { transform: translate(-50%, -50%) rotate(0deg); }
  100% { transform: translate(-50%, -50%) rotate(360deg); }
}
</style>

18.2 experimental / future / features

experimental：实验性功能开关，详见 experimental-features 指南（如 View Transitions API、响应式 props 解构等）。
future：选择启用"将在未来（可能是大版本）成为默认"的新特性，详见 features 指南。
features：Nuxt 的可选 opt-in 能力，同样参考 features 指南。

18.3 compatibilityDate / appConfig / appId

compatibilityDate：为应用指定兼容日期，用于控制 Nitro、Nuxt Image 等模块在不升大版本前提下变更行为的预设。注意同时配置多个 layer 时建议在应用层统一声明。
appConfig：额外应用配置。可通过此选项以编程方式直接提供 app config（获得类型支持），会与 app.config 文件合并作为默认值；app.config.ts 见 app.config 目录文档。
appId：多应用项目中 Nuxt 应用的唯一 id。类型 string，默认 "nuxt-app"。

19. 从源码看配置如何生效：解析器与 Schema

整个 nuxt.config 的可选键、类型与默认值均沉淀在 ConfigSchema 中：

类型定义：NuxtConfig、NuxtConfigInput、DefineNuxtConfig 等导出自 packages/schema/src/types/config.ts，入口文件 packages/schema/src/index.ts 统一再导出 ConfigSchema 与 NuxtConfigSchema。
解析实现：各字段 $resolve/$default 分布在 packages/schema/src/config 目录（common.ts 处理路径、别名、模块；app.ts 处理 app.*；dev.ts、nitro.ts、router.ts、typescript.ts、vite.ts、webpack.ts 等各司其职）。
应用侧运行时入口见 packages/nuxt/src（例如 .nuxt 模板生成、useRuntimeConfig 读取逻辑），构建相关 package 见 packages/vite、packages/webpack、packages/rspack 与 packages/nitro-server。

阅读方式建议：先看 docs/4.api/6.nuxt-config.md 了解完整语义，再对照 packages/schema/src/config/common.ts 中对应字段的 $resolve 逻辑确认相对路径/默认值推导规则，最后用仓库 playground/nuxt.config.ts 或 test/fixtures/basic/nuxt.config.ts 这类真实配置验证写法。工程中按"路径布局 → 应用行为 → 构建体系 → 运行时配置 → 类型与优化"的顺序逐层排查，绝大多数定制需求都能在 nuxt.config.ts 中找到对应开关。

nuxt

the full-stack Vue framework

项目地址：https://gitcode.com/GitHub_Trending/nu/nuxt

登录后查看全文