Nuxt 配置

发现你可以在 nuxt.config.ts 文件中使用的所有选项。

alias

你可以通过定义额外的别名来改进 DX，以便在你的 JavaScript 和 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"
}

注意：在 webpack 上下文中（图片源、CSS——但不是 JavaScript），你必须通过加 ~ 前缀来访问你的别名。

注意：这些别名会自动添加到生成的 TypeScript 配置（.nuxt/tsconfig.app.json、.nuxt/tsconfig.server.json 等）中，因此你可以获得完整的类型支持和路径自动补全。如果你需要进一步扩展生成配置提供的选项，请确保在此处或 nuxt.config 中的 typescript.tsConfig 属性内添加它们。

示例:

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>
// 取消下面的注释
//@import '~style/variables.scss';
//@import '~style/utils.scss';
//@import '~style/base.scss';
body {
  background-image: url('~images/main-bg.jpg');
}
</style>

analyzeDir

运行 nuxt analyze 时 Nuxt 将存储生成文件的目录。

如果指定了相对路径，它将相对于你的 rootDir。

类型: string
默认值: "/<rootDir>/.nuxt/analyze"

app

Nuxt 应用配置。

`baseURL`

你的 Nuxt 应用的基础路径。

例如：

类型: string
默认值: "/"

示例:

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

这也可以在运行时通过设置 NUXT_APP_BASE_URL 环境变量来设置。

示例:

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

由于 Nitro 的限制，相对路径（如 ./）在 nuxt.config.ts 中不直接支持。对于使用相对资源路径的静态托管，请使用以下方法之一：

# 方法 1：构建时的环境变量
NUXT_APP_BASE_URL=./ npm run generate

// 方法 2：Nitro 运行时配置
export default defineNuxtConfig({
  nitro: {
    runtimeConfig: {
      app: {
        baseURL: './',
      },
    },
  },
})

`buildAssetsDir`

已构建站点资源的文件夹名，相对于 baseURL（如果设置了 cdnURL 则相对于它）。这是在构建时设置的，不应在运行时自定义。

类型: string
默认值: "/_nuxt/"

`cdnURL`

用于提供 public 文件夹的绝对 URL（仅生产环境）。

例如：

类型: string
默认值: ""

示例:

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

它可以通过设置 NUXT_APP_CDN_URL 环境变量在运行时设置为不同的值。

示例:

NUXT_APP_CDN_URL=https://mycdn.org/ node .output/server/index.mjs

`head`

为每一页的 <head> 设置默认配置。

类型: object
默认值

{
  "meta": [
    {
      "name": "viewport",
      "content": "width=device-width, initial-scale=1"
    },
    {
      "charset": "utf-8"
    }
  ],
  "link": [],
  "style": [],
  "script": [],
  "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' },
      ],
      // 请注意这是一个可能变化的区域
      style: [
      // <style>:root { color: red }</style>
        { textContent: ':root { color: red }' },
      ],
      noscript: [
      // <noscript>JavaScript is required</noscript>
        { textContent: 'JavaScript is required' },
      ],
    },
  },
})

`keepalive`

页面间 KeepAlive 配置的默认值。

这可以用单个页面上的 definePageMeta 覆盖。仅允许 JSON 可序列化的值。

类型: boolean
默认值: false

参见: Vue KeepAlive

`layoutTransition`

布局过渡的默认值。

这可以用单个页面上的 definePageMeta 覆盖。仅允许 JSON 可序列化的值。

类型: boolean | TransitionProps
默认值: false

参见: Vue Transition 文档

`pageTransition`

页面过渡的默认值。

这可以用单个页面上的 definePageMeta 覆盖。仅允许 JSON 可序列化的值。

类型: boolean | TransitionProps
默认值: false

参见: Vue Transition 文档

`rootAttrs`

自定义 Nuxt 根元素的 id。

类型: object
默认值

{
  "id": "__nuxt"
}

`rootId`

自定义 Nuxt 根元素的 id。

类型: string
默认值: "__nuxt"

`rootTag`

自定义 Nuxt 根元素的标签。

类型: string
默认值: "div"

`spaLoaderTag`

自定义 Nuxt SpaLoader 元素的标签。

类型: string
默认值: "div"

`teleportAttrs`

自定义 Nuxt Teleport 元素的属性。

类型: object
默认值

{
  "id": "teleports"
}

`teleportId`

自定义 Nuxt Teleport 元素的 id。

类型: string
默认值: "teleports"

`teleportTag`

自定义 Nuxt Teleport 元素的标签。

类型: string
默认值: "div"

`viewTransition`

视图过渡的默认值。

这只有在 experimental 对 View Transitions 的支持在你的 nuxt.config 文件中被启用时才生效。这可以用单个页面上的 definePageMeta 覆盖。

类型: boolean
默认值: false

参见: Nuxt View Transition API 文档

appConfig

额外的应用配置

为了编程式使用和类型支持，你可以直接用此选项提供 app config。它会与 app.config 文件合并作为默认值。

appId

对于多应用项目，Nuxt 应用的唯一 id。

默认值为 nuxt-app。

类型: string
默认值: "nuxt-app"

build

共享的构建配置。

`analyze`

Nuxt 允许可视化你的包以及如何优化它们。

设为 true 以启用包分析，或者传入一个带有选项的对象：用于 webpack 或用于 vite。

类型: object
默认值

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

示例:

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

`templates`

建议使用 @nuxt/kit 中的 addTemplate 代替此选项。

类型: array

示例:

export default defineNuxtConfig({
  build: {
    templates: [
      {
        src: '~~/modules/support/plugin.js', // `src` 可以是绝对或相对路径
        dst: 'support.js', // `dst` 相对于项目 `.nuxt` 目录
      },
    ],
  },
})

`transpile`

如果你想用 Babel 转译特定的依赖，可以在此添加它们。transpile 中的每一项可以是一个包名、函数、字符串或匹配依赖文件名的正则对象。

你也可以使用一个函数来进行条件转译。该函数会接收一个对象（{ isDev, isServer, isClient, isModern, isLegacy }）。

类型: array

示例:

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

buildDir

定义你的 Nuxt 构建文件放置的目录。

许多工具假设 .nuxt 是一个隐藏目录（因为它以 . 开头）。如果这有问题，你可以使用此选项来规避。

类型: string
默认值: "/<rootDir>/.nuxt"

示例:

export default defineNuxtConfig({
  buildDir: 'nuxt-build',
})

buildId

与构建匹配的唯一标识符。它可能包含项目当前状态的哈希值。

类型: string
默认值: "4a2e2d30-418f-41df-8e58-ed5df06de7fd"

builder

用于打包你应用 Vue 部分的 builder。

Nuxt 为客户端应用支持多个 builder。默认使用 Vite，但你可以切换到 webpack、Rspack，甚至提供自定义的 builder 实现。

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

使用受支持的 builder：

export default defineNuxtConfig({
  // 默认 - 使用 @nuxt/vite-builder
  // builder: 'vite',

  // 使用 @nuxt/webpack-builder
  // builder: 'webpack',

  // 使用 @nuxt/rspack-builder
  builder: 'rspack',
})

如果你使用 webpack 或 rspack，你需要确保 @nuxt/webpack-builder 或 @nuxt/rspack-builder 已在你的项目中显式安装。

使用自定义 builder 对象：

你可以通过传入一个带有 bundle 函数的对象来提供自定义 builder：

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

      // 构建客户端和服务端 bundle
      await buildClient(nuxt, entry)
      if (nuxt.options.ssr) {
        await buildServer(nuxt, entry)
      }

      // ... 当然，实际比这要复杂一点！
    },
  },
})

创建自定义 builder 包：

要将自定义 builder 创建为单独的包，它应该导出一个 bundle 函数。然后你可以在 nuxt.config.ts 中指定包名：

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

compatibilityDate

为你的应用指定一个兼容性日期。

这用于控制 Nitro、Nuxt Image 以及其他模块中可能在无需主版本升级的情况下改变行为的预设。我们计划在未来改进围绕此特性的工具链。

css

你可以定义希望全局设置的 CSS 文件/模块/库（包含在每个页面中）。

Nuxt 会根据扩展名自动猜测文件类型并使用合适的预处理器。如果需要使用它们，你仍然需要安装所需的 loader。

类型: array

示例:

export default defineNuxtConfig({
  css: [
  // 直接加载一个 Node.js 模块（这里是一个 Sass 文件）。
    'bulma',
    // 项目中的 CSS 文件
    '~/assets/css/main.css',
    // 项目中的 SCSS 文件
    '~/assets/css/main.scss',
  ],
})

debug

设为 true 以启用调试模式。

目前，它会在服务端打印钩子名称和耗时，并在浏览器中记录钩子参数。你也可以将此设为对象来启用特定的调试选项。

类型: boolean
默认值: false

dev

Nuxt 是否运行在开发模式下。

通常你不需要设置此项。

类型: boolean
默认值: false

devServer

`cors`

为开发服务器设置 CORS 选项

`origin`

类型: array
默认值

[
  {}
]

`https`

是否启用 HTTPS。

类型: boolean
默认值: false

示例:

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

`url`

监听的开发服务器 URL。

不应直接设置它，因为它总会被开发服务器用完整的 URL 覆盖（供模块和内部使用）。

类型: string
默认值: "http://localhost:3000"

devServerHandlers

Nitro 仅用于开发的服务器处理器。

类型: array

参见：Nitro 服务端路由文档

devtools

为开发启用 Nuxt DevTools。

devtools 的破坏性变更可能不反映 Nuxt 的版本。

参见：Nuxt DevTools 了解更多。

dir

自定义 Nuxt 使用的默认目录结构。

除非需要，否则最好保持默认。

`assets`

资源目录（在你的构建中以 ~assets 作为别名）。

类型: string
默认值: "app/assets"

`layouts`

布局目录，其中的每个文件都会被自动注册为 Nuxt 布局。

类型: string
默认值: "app/layouts"

`middleware`

中间件目录，其中的每个文件都会被自动注册为 Nuxt 中间件。

类型: string
默认值: "app/middleware"

`modules`

模块目录，其中的每个文件都会被自动注册为 Nuxt 模块。

类型: string
默认值: "modules"

`pages`

将被处理以自动生成应用页面路由的目录。

类型: string
默认值: "app/pages"

`plugins`

插件目录，其中的每个文件都会被自动注册为 Nuxt 插件。

类型: string
默认值: "app/plugins"

`public`

包含你静态文件的目录，这些文件可以通过 Nuxt 服务器直接访问，并在应用生成时被复制到你的 dist 文件夹中。

类型: string
默认值: "public"

`shared`

共享目录。这个目录在应用和服务端之间共享。

类型: string
默认值: "shared"

esbuild

`options`

配置 Nuxt 内部使用并传递给其它 builder（如 Vite 或 webpack）的共享 esbuild 选项。

extends

从多个本地或远程源扩展项目。

值应该是一个字符串或字符串数组，指向源目录或相对于当前配置的配置路径。你可以使用 github:、gh:、gitlab: 或 bitbucket:。

参见：关于扩展配置层的 c12 文档

参见：giget 文档

extensions

应该由 Nuxt 解析器解析的扩展名。

类型: array
默认值

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

hooks

钩子是对 Nuxt 事件的监听器，通常用于模块中，但在 nuxt.config 中也可用。

在内部，钩子遵循使用冒号的命名模式（例如 build:done）。为了方便配置，你也可以将它们结构化为 nuxt.config 中的层级对象（如下）。

示例:

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')
      },
    },
  },
})

ignore

比 ignorePrefix 更可定制：所有匹配 ignore 数组中指定的 glob 模式的文件都会在构建中被忽略。

类型: array
默认值

[
  "**/*.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",
  "**/-*.*"
]

ignoreOptions

将选项直接传给 node-ignore（Nuxt 用于忽略文件的工具）。

参见：node-ignore

示例:

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

ignorePrefix

app/pages/、app/layouts/、app/middleware/ 和 public/ 目录中，任何文件名以 ignorePrefix 指定的前缀开头的文件都会在构建过程中被忽略。这旨在防止某些文件被处理或服务于构建出的应用。默认情况下，ignorePrefix 设为 -，忽略任何以 - 开头的文件。

类型: string
默认值: "-"

imports

配置 Nuxt 如何将组合式函数自动导入到你的应用。

参见：Nuxt 文档

`dirs`

将被自动导入的自定义目录数组。注意此选项不会覆盖默认目录（~~/composables、~~/utils）。

类型: array

示例:

export default defineNuxtConfig({
  imports: {
  // 自动导入在 `~/stores` 中定义的 pinia store
    dirs: ['stores'],
  },
})

`scan`

是否扫描你的 app/composables/ 和 app/utils/ 目录以自动导入组合式函数。由 Nuxt 或其它模块注册的自动导入（例如来自 vue 或 nuxt 的导入）仍会被启用。

类型: boolean
默认值: true

logLevel

构建日志时的日志级别。

在 CI 中或没有可用 TTY 时默认为 'silent'。此选项随后在 Vite 中用作 'silent'，在 webpack 中用作 'none'。

类型: string
默认值: "info"

modules

模块是 Nuxt 的扩展，可以扩展其核心功能并添加无限的集成。

每个模块要么是一个字符串（可以引用一个包，或者是文件路径），要么是一个元组，其中模块作为第一个字符串、选项作为第二个对象，要么是一个内联的模块函数。Nuxt 会尝试使用 node require 路径（在 node_modules 中）解析 modules 数组中的每一项，如果使用 ~~ 别名，则会从项目 rootDir 解析。

类型: array

注意：模块是按顺序执行的，所以顺序很重要。首先加载 nuxt.config.ts 中定义的模块。然后执行在 modules/ 目录中找到的模块，它们按字母顺序加载。

示例:

export default defineNuxtConfig({
  modules: [
  // 使用包名
    '@nuxt/scripts',
    // 相对于你的项目 rootDir
    '~~/custom-modules/awesome.js',
    // 提供选项
    ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
    // 内联定义
    function () {},
  ],
})

modulesDir

用于设置模块目录进行路径解析（例如 webpack 的 resolveLoading、nodeExternals 和 postcss）。

配置路径相对于 options.rootDir（默认为当前工作目录）。如果你的项目组织为 yarn workspace 风格的 monorepo，可能需要设置此字段。

类型: array
默认值

[
  "/<rootDir>/node_modules"
]

示例:

export default defineNuxtConfig({
  modulesDir: ['../../node_modules'],
})

nitro

Nitro 的配置。

参见：Nitro 配置文档

`runtimeConfig`

类型: object
默认值

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

optimization

构建时优化配置。

`asyncTransforms`

直接传给 unctx 的 transformer 的选项，用于保留 await 之后的异步上下文。

`asyncFunctions`

类型: array
默认值

[
  "defineNuxtPlugin",
  "defineNuxtRouteMiddleware"
]

`objectDefinitions`

`defineNuxtComponent`

类型: array
默认值

[
  "asyncData",
  "setup"
]

`defineNuxtPlugin`

类型: array
默认值

[
  "setup"
]

`definePageMeta`

类型: array
默认值

[
  "middleware",
  "validate"
]

`keyedComposables`

需要注入 key 的函数。

只要传给函数的参数数量少于 argumentLength，就会作为最后一个参数注入一个额外的魔法字符串。这个 key 在服务端渲染和客户端水合之间保持稳定。你需要采取措施来处理这个额外的 key。这个 key 基于函数在文件内被调用的位置而唯一。

了解更多关于 keyed 函数。

类型: array
默认值

[
  {
    "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"
  }
]

`treeShake`

从特定的构建中 tree shake（摇树优化）代码。

`composables`

从服务端或客户端构建中 tree shake 组合式函数。

示例:

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

`client`

类型: object
默认值

{
  "vue": [
    "onRenderTracked",
    "onRenderTriggered",
    "onServerPrefetch"
  ],
  "#app": [
    "definePayloadReducer",
    "definePageMeta",
    "onPrehydrate"
  ]
}

`server`

类型: object
默认值

{
  "vue": [
    "onMounted",
    "onUpdated",
    "onUnmounted",
    "onBeforeMount",
    "onBeforeUpdate",
    "onBeforeUnmount",
    "onRenderTracked",
    "onRenderTriggered",
    "onActivated",
    "onDeactivated"
  ],
  "#app": [
    "definePayloadReviver",
    "definePageMeta"
  ]
}

pages

是否在 Nuxt 3 中使用 vue-router 集成。如果你没有提供值，那么当你的源文件夹中有 app/pages/ 目录时，它会被启用。

此外，你可以提供一个 glob 模式或模式数组，以仅扫描某些文件作为页面。

示例:

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

plugins

Nuxt 应用插件的数组。

每个插件可以是一个字符串（可以是文件的绝对或相对路径）。如果它以 .client 或 .server 结尾，则会自动只在相应的上下文中加载。它也可以是一个带有 src 和 mode 键的对象。

类型: array

注意：插件也会从 ~/plugins 目录自动注册，这些插件不需要列在 nuxt.config 中，除非你需要自定义它们的顺序。所有插件都按它们的 src 路径去重。

参见：app/plugins/ 目录文档

示例:

export default defineNuxtConfig({
  plugins: [
    '~/custom-plugins/foo.client.js', // 仅在客户端
    '~/custom-plugins/bar.server.js', // 仅在服务端
    '~/custom-plugins/baz.js', // 客户端 & 服务端
    { src: '~/custom-plugins/both-sides.js' },
    { src: '~/custom-plugins/client-only.js', mode: 'client' }, // 仅在客户端
    { src: '~/custom-plugins/server-only.js', mode: 'server' }, // 仅在服务端
  ],
})

postcss

`plugins`

用于配置 PostCSS 插件的选项。

参见：PostCSS 文档

`autoprefixer`

解析 CSS 并为 CSS 规则添加厂商前缀的插件。

参见：autoprefixer

rootDir

定义你的应用的根目录。

此属性可以被覆盖（例如，运行 nuxt ./my-app/ 会将 rootDir 设置为 ./my-app/ 相对于当前/工作目录的绝对路径）。通常不需要配置此选项。

类型: string
默认值: "/<rootDir>"

routeRules

应用于匹配的服务端路由的全局路由选项。

实验性：这是一个实验性特性，API 未来可能会变化。

参见：Nitro 路由规则文档

router

`options`

传递给 vue-router 的额外路由选项。除了 vue-router 的选项外，Nuxt 还提供了额外的选项来定制路由器（见下）。

注意：只能传递 JSON 可序列化的选项给 Nuxt 配置。要获得更多控制，你可以使用 router.options.ts 文件。

参见：Vue Router 文档

`hashMode`

你可以在 SPA 模式下启用 hash history。在此模式下，路由器在内部传递的实际 URL 之前使用一个井号字符（#）。启用后，URL 永远不会发送到服务器，并且不支持 SSR。

类型: boolean
默认值: false

默认值：false

`scrollBehaviorType`

为 hash 链接自定义滚动行为。

类型: string
默认值: "auto"

默认值：'auto'

此对象的值只能从服务端使用 useRuntimeConfig 访问。它主要应保存_私有_配置，这些配置不会暴露在前端。这可以包括对你的 API 密钥的引用。任何在 public 和 app 下的内容也会被暴露给前端。这些值会在运行时被匹配的环境变量自动替换，例如设置环境变量 NUXT_API_KEY=my-api-key NUXT_PUBLIC_BASE_URL=/foo/ 会覆盖下面示例中的两个值。

类型: object
默认值

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

示例:

export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: '', // 默认为空字符串，在运行时使用 process.env.NUXT_API_KEY 自动设置
    public: {
      baseURL: '', // 同样暴露给前端。
    },
  },
})

server

Nuxt 服务端 builder 的配置。

`builder`

指定用于打包应用服务端部分的服务端 builder。

默认情况下，Nuxt 使用 @nuxt/nitro-server，它提供独立的 Nitro 集成。这种架构支持不同的 Nitro 集成模式，例如将 Nitro 用作 Vite 插件（配合 Vite Environment API）。

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

此选项用于内部使用，API 尚未最终确定。在依赖当前实现之前，请先提交 issue。

serverDir

定义你的 Nuxt 应用的服务端目录，Nitro 路由、中间件和插件保存在那里。

如果指定了相对路径，它将相对于你的 rootDir。

类型: string
默认值: "/<rootDir>/server"

serverHandlers

Nitro 服务端处理器。

每个处理器接受以下选项：

handler：定义处理器的文件路径。
route：处理器可用的路由。这遵循 rou3 的约定。
method：应该被处理的请求的 HTTP 方法。
middleware：指定它是否是中间件处理器。
lazy：指定是否使用懒加载来导入处理器。
类型: array

参见：server/ 目录文档

注意：来自 server/api、server/middleware 和 server/routes 的文件会被 Nuxt 自动注册。

示例:

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

sourcemap

配置是否为服务端和/或客户端 bundle 生成 sourcemap 以及如何生成。

如果设置为单个布尔值，该值同时适用于服务端和客户端。此外，'hidden' 选项对服务端和客户端也都可用。客户端和服务端都可用选项：

true：生成 sourcemap 并在最终 bundle 中包含源码引用。
false：不生成任何 sourcemap。
'hidden'：生成 sourcemap 但不在最终 bundle 中包含引用。
类型: object
默认值

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

spaLoadingTemplate

布尔值，或一个 HTML 文件路径，其内容会被插入到任何以 ssr: false 渲染的 HTML 页面中。

如果未设置，它将使用你某个 layer 中的 ~/spa-loading-template.html 文件（如果存在）。
如果为 false，则不会加载任何 SPA 加载指示器。
如果为 true，Nuxt 会在你的某个 layer 中寻找 ~/spa-loading-template.html 文件，或者使用默认的 Nuxt 图片。

一些好的 spinner 来源是 SpinKit 或 SVG Spinners。

默认值: null

示例：~/spa-loading-template.html

<!-- https://github.com/barelyhuman/snips/blob/dev/pages/css-loader.md -->
<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>

srcDir

定义你的 Nuxt 应用的源目录。

如果指定了相对路径，它将相对于 rootDir。

类型: string
默认值: "app"（Nuxt 4），"."（使用 compatibilityMode: 3 的 Nuxt 3）

示例:

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

这期望以下文件夹结构：

-| 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

ssr

是否启用 HTML 渲染——可以是动态渲染（在服务端模式下），也可以在生成时渲染。如果设为 false，生成的页面将没有内容。

类型: boolean
默认值: true

telemetry

手动禁用 nuxt 遥测。

参见：Nuxt Telemetry 了解更多。

test

你的应用是否正在进行单元测试。

类型: boolean
默认值: false

theme

从本地或远程源扩展项目。

值应该是一个字符串，指向源目录或相对于当前配置的配置路径。你可以使用 github:、gitlab:、bitbucket: 或 https:// 从远程 git 仓库扩展。

类型: string

typescript

Nuxt 的 TypeScript 集成配置。

`appTsConfig`

你可以使用此选项扩展生成的 .nuxt/tsconfig.app.json（以及遗留的 .nuxt/tsconfig.json）TypeScript 配置。此处设置的选项优先于 tsConfig。

参见：tsconfig.json 信息

`builder`

为你的项目包含哪些 builder 类型。

默认情况下，Nuxt 根据 builder 选项（默认为 'vite'）推断此项，但你可以关闭 builder 环境类型（设为 false）来完全自己处理，或选择 'shared' 选项。'shared' 选项建议给模块作者，他们会想支持多种可能的 builder。

默认值: null

`hoist`

在 compilerOptions.paths 中生成深层别名的模块。这还不支持子路径。当在 pnpm monorepo 中使用 shamefully-hoist=false 的 Nuxt 时，这可能有必要。

类型: array
默认值

[
  "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"
]

`includeWorkspace`

在 Nuxt 项目中包含父工作区。对主题和模块作者最有用。

类型: boolean
默认值: false

`nodeTsConfig`

你可以使用此选项扩展生成的 .nuxt/tsconfig.node.json TypeScript 配置。

参见：tsconfig.json 信息

`serverTsConfig`

你可以使用此选项扩展生成的 .nuxt/tsconfig.server.json TypeScript 配置。此处设置的选项优先于 tsConfig。

参见：tsconfig.json 信息

`sharedTsConfig`

你可以使用此选项扩展生成的 .nuxt/tsconfig.shared.json TypeScript 配置。

参见：tsconfig.json 信息

`shim`

生成一个 *.vue 类型垫片。

我们反而建议让官方 Vue 扩展为你的组件生成准确的类型。请注意，如果你使用了其他库（例如 ESLint），它们无法理解 .vue 文件的类型，你可能希望将此设为 true。

类型: boolean
默认值: false

`strict`

TypeScript 带有某些检查，以给你的程序提供更高的安全性与分析能力。一旦你已将代码库转换为 TypeScript，就可以开始启用这些检查以获得更大的安全性。阅读更多

类型: boolean
默认值: true

`tsConfig`

你可以使用此选项用共享选项扩展生成的 tsconfig 文件。compilerOptions 适用于所有生成的 tsconfig（.nuxt/tsconfig.app.json、.nuxt/tsconfig.server.json、.nuxt/tsconfig.node.json 和 .nuxt/tsconfig.shared.json），而 include、exclude 和 vueCompilerOptions 仅适用于 .nuxt/tsconfig.app.json（以及遗留的 .nuxt/tsconfig.json）。两组 compilerOptions 是例外：DOM 和 Vue 特定的选项（如 lib、jsx 和 jsxImportSource）仅适用于 .nuxt/tsconfig.app.json，而 types、paths 和 noEmit 由 Nuxt 按上下文管理，所以不能为 node、shared 和 server 的 tsconfig 全局设置。使用 appTsConfig、serverTsConfig、nodeTsConfig 或 sharedTsConfig 进行上下文特定的覆盖；它们优先于此选项。

参见：tsconfig.json 信息

`typeCheck`

启用构建时类型检查。

如果设为 true，这将在开发时执行类型检查。你可以通过将值设为 build 来将其限制为构建时类型检查。需要将 typescript 和 vue-tsc 作为开发依赖安装。

类型: boolean
默认值: false

参见：Nuxt TypeScript 文档

unhead

一个允许我们配置 unhead nuxt 模块的对象。

`legacy`

为 unhead 模块启用遗留兼容模式。这会应用以下更改：

禁用 Capo.js 排序
添加 DeprecationsPlugin：支持 hid、vmid、children、body
添加 PromisesPlugin：支持将 promise 作为输入
类型: boolean
默认值: false

参见：unhead 迁移文档

示例:

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

`renderSSRHeadOptions`

一个会传给 renderSSRHead 以自定义输出的对象。

类型: object
默认值

{
  "omitLineBreaks": false
}

示例:

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

vite

将直接传给 Vite 的配置。

顶层的 vite 选项在客户端和服务端环境之间共享。使用 $client 和 $server 提供环境特定的配置，它们会被合并进各自的构建中。

示例:

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

参见：Vite 配置文档了解更多。请注意，并非所有 vite 选项在 Nuxt 中都受支持。

`$client`

将被合并进 Vite 客户端（浏览器）构建配置的配置。

类型: object

`$server`

将被合并进 Vite 服务端构建配置的配置。

类型: object

`build`

`assetsDir`

类型: string
默认值: "_nuxt/"

`emptyOutDir`

类型: boolean
默认值: false

`cacheDir`

类型: string
默认值: "/<rootDir>/node_modules/.cache/vite"

`clearScreen`

类型: boolean
默认值: true

`define`

类型: object
默认值

{
  "__VUE_PROD_HYDRATION_MISMATCH_DETAILS__": false,
  "process.dev": false,
  "import.meta.dev": false,
  "process.test": false,
  "import.meta.test": false
}

`esbuild`

类型: object
默认值

{
  "target": "esnext",
  "jsxFactory": "h",
  "jsxFragment": "Fragment",
  "tsconfigRaw": {}
}

`mode`

类型: string
默认值: "production"

`optimizeDeps`

`esbuildOptions`

类型: object
默认值

{
  "target": "esnext",
  "jsxFactory": "h",
  "jsxFragment": "Fragment",
  "tsconfigRaw": {}
}

`exclude`

类型: array
默认值

[
  "vue-demi"
]

`publicDir`

`resolve`

`extensions`

类型: array
默认值

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

`root`

类型: string
默认值: "/<rootDir>"

`server`

`fs`

`allow`

类型: array
默认值

[
  "/<rootDir>/.nuxt",
  "/<rootDir>/app",
  "/<rootDir>",
  "/<workspaceDir>"
]

`vue`

`features`

`propsDestructure`

类型: boolean
默认值: true

`isProduction`

类型: boolean
默认值: true

`script`

`hoistStatic`

`template`

`compilerOptions`

类型: object

`transformAssetUrls`

类型: object
默认值

{
  "video": [
    "src",
    "poster"
  ],
  "source": [
    "src"
  ],
  "img": [
    "src"
  ],
  "image": [
    "xlink:href",
    "href"
  ],
  "use": [
    "xlink:href",
    "href"
  ]
}

`vueJsx`

类型: object
默认值

{
  "isCustomElement": {
    "$schema": {
      "title": "",
      "description": "",
      "tags": []
    }
  }
}

vue

Vue.js 配置

`compilerOptions`

将传给 Vue 编译器的选项，在构建时生效。

参见：Vue 文档

`config`

可以全局配置 Vue 应用。只有可序列化的选项可以在你的 nuxt.config 中设置。所有其他选项应在运行时在 Nuxt 插件中设置。

参见：Vue app config 文档

`propsDestructure`

为 defineProps 启用响应式解构

类型: boolean
默认值: true

`runtimeCompiler`

在运行时 bundle 中包含 Vue 编译器。

启用此项允许组件在运行时编译模板（例如字符串 template 选项，或通过数据提供的模板）。

类型: boolean
默认值: false

运行时模板编译会将编译后的模板作为 JavaScript 执行。绝不要编译由用户提供的或不可信输入构建的模板；这样做等同于 eval，可能导致跨站脚本或远程代码执行。参见 Vue 安全指南。

`transformAssetUrls`

`image`

类型: array
默认值

[
  "xlink:href",
  "href"
]

`img`

类型: array
默认值

[
  "src"
]

`source`

类型: array
默认值

[
  "src"
]

`use`

类型: array
默认值

[
  "xlink:href",
  "href"
]

`video`

类型: array
默认值

[
  "src",
  "poster"
]

watch

watch 属性让你定义一些模式，当它们改变时会重启 Nuxt 开发服务器。

它是一个字符串或正则表达式的数组。字符串应该是绝对路径，或相对于 srcDir（以及任何 layer 的 srcDir）。正则表达式将匹配相对于项目 srcDir（以及任何 layer 的 srcDir）的路径。

类型: array

类型: boolean
默认值: true

`ignorePermissionErrors`

类型: boolean
默认值: true

类型: number
默认值: 1000

webpack

`aggressiveCodeRemoval`

硬替换 typeof process、typeof window 和 typeof document 以 tree-shake bundle。

类型: boolean
默认值: false

`analyze`

如果你使用 webpack，Nuxt 使用 webpack-bundle-analyzer 来可视化你的包以及如何优化它们。

设为 true 以启用包分析，或者传入一个带有选项的对象：用于 webpack 或用于 vite。

类型: object
默认值

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

示例:

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

`cssSourceMap`

启用 CSS source map 支持（开发模式下默认为 true）。

类型: boolean
默认值: false

`devMiddleware`

参见 webpack-dev-middleware 了解可用选项。

`stats`

类型: string
默认值: "none"

`experiments`

配置 webpack experiments

`extractCSS`

启用公共 CSS 提取。

底层使用 mini-css-extract-plugin，你的 CSS 会被提取到独立的文件中，通常每个组件一个。这允许分别缓存你的 CSS 和 JavaScript。

类型: boolean
默认值: true

示例:

export default defineNuxtConfig({
  webpack: {
    extractCSS: true,
    // 或
    extractCSS: {
      ignoreOrder: true,
    },
  },
})

如果你想将所有 CSS 提取到单个文件中，有一个变通方法。不过，请注意不推荐将所有内容提取到单个文件。提取到多个 CSS 文件对缓存和预加载隔离更好。它通过只下载和解析所需的资源还可以改善页面性能。

示例:

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

`filenames`

自定义 bundle 文件名。

要进一步了解 manifest 的使用，请查看 webpack 文档。

注意：在生产环境中使用非哈希文件名时要小心，因为大多数浏览器会缓存资源，并在首次加载时检测不到变化。

此示例将花哨的 chunk 名称改为数字 id：

示例:

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

`app`

类型: function

`chunk`

类型: function

`css`

类型: function

`font`

类型: function

`img`

类型: function

`video`

类型: function

`friendlyErrors`

设为 false 以禁用 FriendlyErrorsWebpackPlugin 提供的遮罩层。

类型: boolean
默认值: true

`esModule`

类型: boolean
默认值: false

`importLoaders`

类型: number
默认值: 0

`url`

`filter`

类型: function

`cssModules`

参见 css-loader 了解可用选项。

`esModule`

类型: boolean
默认值: false

`importLoaders`

类型: number
默认值: 0

`modules`

`localIdentName`

类型: string
默认值: "[local]_[hash:base64:5]"

`url`

`filter`

类型: function

`esbuild`

类型: object
默认值

{
  "target": "esnext",
  "jsxFactory": "h",
  "jsxFragment": "Fragment",
  "tsconfigRaw": {}
}

参见：esbuild loader

`file`

参见：file-loader 选项

默认值:

{ "esModule": false }

`esModule`

类型: boolean
默认值: false

`limit`

类型: number
默认值: 1000

`fontUrl`

参见：file-loader 选项

默认值:

{ "esModule": false }

`esModule`

类型: boolean
默认值: false

`limit`

类型: number
默认值: 1000

`imgUrl`

参见：file-loader 选项

默认值:

{ "esModule": false }

`esModule`

类型: boolean
默认值: false

`limit`

类型: number
默认值: 1000

`less`

默认值

{
  "sourceMap": false
}

参见：less-loader 选项

`pugPlain`

参见：pug 选项

`sass`

参见：sass-loader 选项

默认值:

{
  "sassOptions": {
    "indentedSyntax": true
  }
}

`sassOptions`

`indentedSyntax`

类型: boolean
默认值: true

`scss`

默认值

{
  "sourceMap": false
}

参见：sass-loader 选项

`stylus`

默认值

{
  "sourceMap": false
}

参见：stylus-loader 选项

`vue`

参见 vue-loader 了解可用选项。

`compilerOptions`

类型: object

`propsDestructure`

类型: boolean
默认值: true

`transformAssetUrls`

类型: object
默认值

{
  "video": [
    "src",
    "poster"
  ],
  "source": [
    "src"
  ],
  "img": [
    "src"
  ],
  "image": [
    "xlink:href",
    "href"
  ],
  "use": [
    "xlink:href",
    "href"
  ]
}

`vueStyle`

默认值

{
  "sourceMap": false
}

`optimization`

配置 webpack optimization。

`minimize`

将 minimize 设为 false 以禁用所有压缩器。（默认在开发模式下禁用）。

类型: boolean
默认值: true

`minimizer`

你可以将 minimizer 设置为自定义的插件数组。

`runtimeChunk`

类型: string
默认值: "single"

`splitChunks`

`automaticNameDelimiter`

类型: string
默认值: "/"

`cacheGroups`

`chunks`

类型: string
默认值: "all"

`optimizeCSS`

OptimizeCSSAssets 插件选项。

当 extractCSS 启用时默认为 true。

类型: boolean
默认值: false

参见：css-minimizer-webpack-plugin 文档。

`plugins`

添加 webpack 插件。

类型: array

示例:

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

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

`postcss`

自定义 PostCSS Loader。与 postcss-loader 选项相同。

`postcssOptions`

`plugins`

类型: object
默认值

{
  "autoprefixer": {},
  "cssnano": {}
}

`profile`

在 webpackbar 中启用性能分析器。

通常它通过 CLI 参数 --profile 启用。

类型: boolean
默认值: false

参见：webpackbar。

`serverURLPolyfill`

用于提供 URL 和 URLSearchParams 的 polyfill 库。

默认为 'url'（参见包）。

类型: string
默认值: "url"

`warningIgnoreFilters`

用于隐藏构建警告的过滤器。

类型: array

workspaceDir

定义你的应用的工作区目录。

这通常用于 monorepo 设置中。Nuxt 会尝试自动检测你的工作区目录，但你可以在此处覆盖它。通常不需要配置此选项。

类型: string
默认值: "/<workspaceDir>"