Nuxt 配置

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

alias

你可以通过定义额外的别名来提升开发体验，以便在 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 在运行 nuxt analyze 时存放生成文件的目录。

如果指定的是相对路径，则相对于你的 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

`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 根元素属性。

类型：object
默认值

{
  "id": "__nuxt"
}

`rootId`

自定义 Nuxt 根元素 id。

类型：string
默认值："__nuxt"

`rootTag`

自定义 Nuxt 根元素标签。

类型：string
默认值："div"

`spaLoaderAttrs`

自定义 Nuxt SPA 加载模板元素属性。

类型：object
默认值：

{
"id": "__nuxt-loader"
}

`id`

类型：string
默认值："__nuxt-loader"

`spaLoaderTag`

自定义 Nuxt SpaLoader 元素标签。

类型：string
默认值："div"

`teleportAttrs`

自定义 Nuxt Teleport 元素属性。

类型：object
默认值

{
  "id": "teleports"
}

`teleportId`

自定义 Nuxt Teleport 元素 id。

类型：string
默认值："teleports"

`teleportTag`

自定义 Nuxt Teleport 元素标签。

类型：string
默认值："div"

`viewTransition`

视图切换的默认值。

仅当在 nuxt.config 文件中启用实验性支持视图切换时生效。可通过单个页面的 definePageMeta 覆盖。

类型：boolean
默认值：false

参见：Nuxt 视图切换 API 文档

appConfig

额外的应用配置

为编程使用和类型支持，你可以通过此选项直接提供应用配置。该配置会与 app.config 文件的默认值合并。

`nuxt`

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 应用部分的构建器。

Nuxt 支持多种客户端构建器。默认使用 Vite，但你可以切换到 webpack、Rspack 或自定义构建器实现。

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

使用自定义构建器对象：

传入带有 bundle 函数的自定义构建器对象：

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

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

      // … 当然，实际更复杂！
    },
  },
})

创建自定义构建器包：

作为独立包创建自定义构建器，应导出 bundle 函数。然后在 nuxt.config.ts 指定包名：

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

compatibilityDate

为应用指定兼容性日期。

此选项用于控制 Nitro、Nuxt Image 及其他模块的预设行为，防止在非大版本更新时行为变化。计划未来增强此功能的工具支持。

components

配置 Nuxt 组件自动注册。

这里配置的目录中的组件可在所有页面、布局（及其他组件）中无须显式导入即可使用。

类型：object
默认值

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

参见：app/components/ 目录文档

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
默认值

[
  {}
]

`host`

开发服务器监听的主机。

`https`

是否启用 HTTPS。

类型：boolean
默认值：false

示例：

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

`loadingTemplate`

显示加载界面的模板。

类型：function

`port`

开发服务器监听端口。

类型：number
默认值：3000

`url`

开发服务器监听的 URL。

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

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

devServerHandlers

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

类型：array

参见：Nitro 服务器路由文档

devtools

启用 Nuxt DevTools 进行开发。

DevTools 的破坏性更改可能与 Nuxt 版本不同步。

参见：Nuxt DevTools 获取更多信息。

dir

自定义 Nuxt 默认目录结构。

除非必要，建议保持默认。

`app`

类型：string
默认值："app"

`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 内部以及转给其他构建器（如 Vite 或 webpack）的共享 esbuild 选项。

`jsxFactory`

类型：string
默认值："h"

`jsxFragment`

类型：string
默认值："Fragment"

`target`

类型：string
默认值："esnext"

`tsconfigRaw`

类型：object

experimental

了解更多关于 Nuxt 实验性特性。

extends

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

值应为指向源目录或相对当前配置的配置路径的字符串或字符串数组。支持使用 github:、gh:、gitlab: 或 bitbucket: 。

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

参见：giget 文档

extensions

Nuxt 解析器应解析的文件扩展名。

类型：array
默认值

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

features

了解更多关于 Nuxt 的可选特性。

future

了解更多关于选择性启用未来将成为默认的新特性（可能是大版本）的内容。

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/ 目录下，文件名以此前缀开头的文件将在构建过程中被忽略。用于防止某些文件被处理或在构建应用时被服务。默认前缀为 -，会忽略所有以 - 开头的文件。

类型：string
默认值："-"

imports

配置 Nuxt 组件自动导入。

参见：Nuxt 文档

`dirs`

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

类型：array

示例：

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

`global`

类型：boolean
默认值：false

`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），若以 ~~ 路径别名使用，则从项目 rootDir 解析。

类型：array

注意：模块按顺序执行，顺序重要。首先加载 nuxt.config.ts 中定义的模块，然后依字母顺序加载 modules/ 目录内的模块。

示例：

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

modulesDir

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

路径相对于 options.rootDir（默认当前工作目录）。在使用 yarn workspace 类型的 mono-repo 时可能需要配置。

类型：array
默认值

[
  "/<rootDir>/node_modules"
]

示例：

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

nitro

Nitro 的配置。

参见：Nitro 配置文档

`routeRules`

类型：object

`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 对 SSR 和客户端 hydration 是稳定的。你需要处理此额外 key。key 基于函数在文件中的位置唯一。

了解更多关于带 key 的函数。

类型：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`

对特定构建移除未使用代码。

`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

`order`

PostCSS 插件的排序策略。

类型：function

`plugins`

配置 PostCSS 插件选项。

参见：PostCSS 文档

`autoprefixer`

用于解析 CSS 并自动添加前缀。

参见：autoprefixer

`cssnano`

类型：object

参见：cssnano 配置选项

rootDir

定义你的应用根目录。

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

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

routeRules

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

实验性功能：该功能及接口可能未来会改动。

参见：Nitro 路由规则文档

router

`options`

传递给 vue-router 的额外路由器选项。在 vue-router 选项基础上，Nuxt 提供额外路由器自定义选项（见下文）。

注意：Nuxt 配置中只能传递 JSON 序列化的选项。想要更精细控制，可使用 router.options.ts 文件。

参见：Vue Router 文档

`hashMode`

在 SPA 模式下启用 hash 历史模式。此模式路由使用 # 前缀的 URL，URL 不会发送至服务器且不支持 SSR。

类型：boolean
默认值：false

`scrollBehaviorType`

针对哈希链接自定义滚动行为。

类型：string
默认值："auto"

runtimeConfig

运行时配置，允许将动态配置和环境变量传递给 Nuxt 应用上下文。

此对象值仅可通过服务器端的 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`

指定服务器端应用部分的构建器。

默认使用 @nuxt/nitro-server，提供独立的 Nitro 集成架构，同时也支持多种 Nitro 集成模式，如将 Nitro 作为 Vite 插件。

类型：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

配置是否以及如何为服务器和/或客户端包生成源码映射。

若为单个布尔值，则同时应用于服务器和客户端。也支持 'hidden' 选项。选项含义如下：

true：生成源码映射并包含资源引用。
false：不生成源码映射。
'hidden'：生成源码映射但不包含资源引用。
类型：object
默认值

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

spaLoadingTemplate

布尔值或 HTML 文件路径。内容会插入至任何设置了 ssr: false 的 HTML 页面。

若未设置，将使用位于层中的 ~/spa-loading-template.html（如果存在）。
若为 false，不加载 SPA 加载指示器。
若为 true，Nuxt 会查找层中的 ~/spa-loading-template.html 文件，或使用默认 Nuxt 图片。推荐的加载动画资源有 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）、"."（兼容模式 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 集成配置。

`builder`

包含项目所需的构建器类型。

默认 Nuxt 基于 builder 选项自动推断（默认为 vite），但你可以关闭构建器环境类型（设为 false）自行处理，或使用 shared 选项。

推荐模块作者使用 shared 选项，以兼容多构建器。

默认值：null

`hoist`

在 compilerOptions.paths 中为部分模块生成功能性别名。目前不支持子路径。若使用 pnpm 并禁用 shamefully-hoist，可能需要此项。

类型：array
默认值

[
  "nitropack/types",
  "nitropack/runtime",
  "nitropack",
  "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

`shim`

生成 .vue 类型声明文件（shim）。

推荐使用官方 Vue 插件生成准确组件类型声明。如果你使用 ESLint 等无法识别 .vue 类型的工具，可能需要开启。

类型：boolean
默认值：false

`strict`

TypeScript 提供的更严格安全检查。转换完项目后，可以启用获得更高安全。详见

类型：boolean
默认值：true

`tsConfig`

可用于扩展生成的 TypeScript 配置（.nuxt/tsconfig.app.json，.nuxt/tsconfig.server.json 等）。

`typeCheck`

启用构建时类型检查。

若设为 true，则在开发时进行类型检查。可设置为 build 仅在构建时检查。需要安装 typescript 和 vue-tsc 作为开发依赖。

类型：boolean
默认值：false

参见：Nuxt TypeScript 文档

unhead

用于配置 Nuxt 的 unhead 模块的对象。

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

类型：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"
]

类型：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": []
    }
  }
}

类型：boolean
默认值：true

`runtimeCompiler`

在运行时包内包含 Vue 编译器。

类型：boolean
默认值：false

`transformAssetUrls`

`image`

类型：array
默认值

[
  "xlink:href",
  "href"
]

`img`

类型：array
默认值

[
  "src"
]

`source`

类型：array
默认值

[
  "src"
]

`use`

类型：array
默认值

[
  "xlink:href",
  "href"
]

`video`

类型：array
默认值

[
  "src",
  "poster"
]

watch

通过此属性定义模式，匹配的文件变更时会重启 Nuxt 开发服务器。

是字符串或正则表达式数组。字符串为绝对路径或相对 srcDir（含层的 srcDir）路径。正则表达式匹配相对于项目 srcDir（含层的 srcDir）的路径。

类型：array

类型：boolean
默认值：true

`ignorePermissionErrors`

类型：boolean
默认值：true

类型：number
默认值：1000

webpack

`aggressiveCodeRemoval`

硬替换 typeof process、typeof window 和 typeof document，以利于代码树摇。

类型：boolean
默认值：false

`analyze`

启用 webpack 包分析，或传入带选项的对象。

类型：object
默认值

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

示例：

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

`cssSourceMap`

启用 CSS 源码映射（开发模式下默认为 true）。

类型：boolean
默认值：false

`devMiddleware`

配置详见webpack-dev-middleware。

`stats`

类型：string
默认值："none"

`experiments`

配置webpack 实验特性

`extractCSS`

启用公共 CSS 提取。

基于 mini-css-extract-plugin，CSS 通常会被分离到每个组件对应文件。支持独立缓存 CSS 与 JS。

类型：boolean
默认值：true

示例：

export default defineNuxtConfig({
  webpack: {
    extractCSS: true,
    // 也可写为
    extractCSS: {
      ignoreOrder: true,
    },
  },
})

如需将所有 CSS 提取到单文件，有非官方方案。通常不推荐单一文件提取，拆分文件更利于缓存和性能优化。

示例：

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

`filenames`

自定义构建文件名。

为更好理解清单用法，查看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 优化

`minimize`

设置为 false 禁用所有最小化器（开发时默认禁用）。

类型：boolean
默认值：true

`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 profiler。

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

类型：boolean
默认值：false

参见：webpackbar。

`serverURLPolyfill`

加载用于提供 URL 和 URLSearchParams 的 polyfill 库。

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

类型：string
默认值："url"

`warningIgnoreFilters`

过滤构建时忽略的警告。

类型：array

workspaceDir

定义应用工作区目录。

通常用于 mono-repo 设置。Nuxt 会尝试自动检测工作目录，但你可以在此覆盖。通常无需配置。

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

报告问题或者在 GitHub 上编辑此页面

导入 meta

使用 `import.meta` 了解你的代码在哪运行。

Hello World

一个最小的 Nuxt 应用程序只需要 `app.vue` 和 `nuxt.config.js` 文件。