---
title: "Nuxt 配置"
description: "探索你可以在 nuxt.config.ts 文件中使用的所有选项。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config"
---
# Nuxt 配置

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

## 别名

你可以通过定义额外的别名来提升开发体验，以便在 JavaScript 和 CSS 中访问自定义目录。

- **类型**：`object`
- **默认值**

```json
{
  "~": "/<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
<!-- @case-police-ignore tsConfig -->

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

**示例**：

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

```html
<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`
- **默认值：**`"/"`

**示例**：

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

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

**示例**：

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

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

```bash
# 选项 1：在构建时通过环境变量设置
NUXT_APP_BASE_URL=./ npm run generate
```

```ts
// Option 2: Runtime config
export default defineNuxtConfig({
  runtimeConfig: {
    app: {
      baseURL: './',
    },
  },
})
```
::

### `buildAssetsDir`

构建后站点资源文件夹名，相对于 `baseURL`（或 `cdnURL`，如果设置了）。该选项在构建时设置，运行时不应自定义。

- **类型**：`string`
- **默认值：**`"/_nuxt/"`

### `cdnURL`

用于生产环境服务 public 文件夹的绝对 URL。

例如：

- **类型**：`string`
- **默认值：**`""`

**示例**：

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

可通过设置环境变量 `NUXT_APP_CDN_URL` 在运行时更改此值。

**示例**：

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

### `head`

为每个页面设置默认的 `<head>` 配置。

- **类型**：`object`
- **默认值**

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

**示例**：

```ts
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://my-awesome-lib.css">
        { rel: 'stylesheet', href: 'https://awesome-lib.css' },
      ],
      // 请注意，这部分内容可能会变更
      style: [
      // <style>:root { color: red }</style>
        { textContent: ':root { color: red }' },
      ],
      noscript: [
      // <noscript>需要 JavaScript</noscript>
        { textContent: '需要 JavaScript' },
      ],
    },
  },
})
```

### `keepalive`

页面间 KeepAlive 配置的默认值。

可以通过单个页面的 `definePageMeta` 覆盖。仅允许 JSON 可序列化的值。

- **类型**：`boolean`
- **默认值：**`false`

**参见**：[Vue KeepAlive](https://vue.zhcndoc.com/api/built-in-components#keepalive)

### `layoutTransition`

布局切换的默认值。

可通过单个页面的 `definePageMeta` 覆盖。仅允许 JSON 可序列化的值。

- **类型**：`boolean | TransitionProps`
- **默认值：**`false`

**参见**：[Vue Transition 文档](https://vue.zhcndoc.com/api/built-in-components#transition)

### `pageTransition`

页面切换的默认值。

可通过单个页面的 `definePageMeta` 覆盖。仅允许 JSON 可序列化的值。

- **类型**：`boolean | TransitionProps`
- **默认值：**`false`

**参见**：[Vue Transition 文档](https://vue.zhcndoc.com/api/built-in-components#transition)

### `rootAttrs`

自定义 Nuxt 根元素属性。

- **类型**：`object`
- **默认值**

```json
{
  "id": "__nuxt"
}
```

### `rootId`

自定义 Nuxt 根元素 id。

- **类型**：`string`
- **默认值：**`"__nuxt"`

### `rootTag`

自定义 Nuxt 根元素标签。

- **类型**：`string`
- **默认值：**`"div"`

### `spaLoaderAttrs`

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

- **类型**：`object`
- **默认值：**

```json
{
"id": "__nuxt-loader"
}
```

#### `id`

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

### `spaLoaderTag`

自定义 Nuxt SpaLoader 元素标签。

- **类型**：`string`
- **默认值：**`"div"`

### `teleportAttrs`

自定义 Nuxt Teleport 元素属性。

- **类型**：`object`
- **默认值**

```json
{
  "id": "teleports"
}
```

### `teleportId`

自定义 Nuxt Teleport 元素 id。

- **类型**：`string`
- **默认值：**`"teleports"`

### `teleportTag`

自定义 Nuxt Teleport 元素标签。

- **类型**：`string`
- **默认值：**`"div"`

### `viewTransition`

视图切换的默认值。

仅当在 [nuxt.config 文件中启用](https://nuxt.zhcndoc.com/docs/4.x/getting-started/transitions#view-transitions-api-experimental) View Transitions 的**实验性**支持时，此选项才会生效。
可以通过单个页面的 `definePageMeta` 覆盖此选项。

- **类型**：`boolean`
- **默认值：**`false`

**参见**：[Nuxt View Transition API 文档](https://nuxt.zhcndoc.com/docs/4.x/getting-started/transitions#view-transitions-api-experimental)

## appConfig

额外的应用配置

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

### `nuxt`

## appId

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

默认值为 `nuxt-app`。

- **类型**：`string`
- **默认值：**`"nuxt-app"`。

## build

共享的构建配置。

### `analyze`

Nuxt 允许可视化你的包体及如何优化。

设置为 `true` 开启包分析，或传入带选项的对象：[webpack 的配置](https://github.com/webpack/webpack-bundle-analyzer#options-for-plugin) 或 [vite 的配置](https://github.com/btd/rollup-plugin-visualizer#options)。

- **类型**：`object`
- **默认值**

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

**示例**：

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

### `templates`

建议使用 `@nuxt/kit` 的 `addTemplate`，而非直接使用此选项。

- **类型**：`array`

**示例**：

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

### `transpile`

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

你也可以用函数条件转译。该函数接收一个对象参数 ()。

- **类型**：`array`

**示例**：

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

## buildDir

定义构建后 Nuxt 文件存放的目录。

很多工具假设 `.nuxt` 是隐藏文件夹（因为以 `.` 开头）。如果这是问题，你可以用此选项修改。

- **类型**：`string`
- **默认值：**`"/<rootDir>/.nuxt"`

**示例**：

```ts
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"`

**使用支持的构建器：**

```ts
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` 函数的自定义构建器对象：

```ts
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` 指定包名：

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

## compatibilityDate

为应用指定兼容性日期。

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

## 组件

配置 Nuxt 组件自动注册。

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

- **类型**：`object`
- **默认值**

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

**参见**：[`app/components/` 目录文档](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/components)

## css

定义想要全局设置的 CSS 文件/模块/库（将被包含于每个页面）。

Nuxt 会根据文件扩展名自动判断类型并使用相应预处理器。你仍需要安装所需的 loader。

- **类型**：`array`

**示例**：

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

## 调试

设置为 `true` 启用调试模式。

目前会在服务器打印钩子名和时间，浏览器打印钩子参数。也可以设置为对象启用特定调试项。

- **类型**：`boolean`
- **默认值：**`false`。

## dev

指定 Nuxt 是否处于开发模式。

一般无需设置。

- **类型**：`boolean`
- **默认值：**`false`。

## devServer

### `cors`

为开发服务器设置 CORS 选项。

#### `origin`

- **类型**：`array`
- **默认值**

```json
[
  {}
]
```

### `host`

开发服务器监听的主机。

### `https`

是否启用 HTTPS。

- **类型**：`boolean`
- **默认值：**`false`

**示例**：

```ts
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 仅开发时用的服务器处理器。

- **类型**：`数组`

**参见**：[Nitro 服务器路由文档](https://nitro.zhcndoc.com/guide/routing)

## 开发工具

启用 Nuxt DevTools 进行开发。

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

**参见**：[Nuxt DevTools](https://devtools.nuxt.com/) 获取更多信息。

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

- **类型**：`字符串`
- **默认值：**`"h"`

#### `jsxFragment`

- **类型**：`字符串`
- **默认值：**`"Fragment"`

#### `target`

- **类型**：`字符串`
- **默认值：**`"esnext"`

#### `tsconfigRaw`

- **类型**：`对象`

## 实验性

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/experimental-features"}
进一步了解 Nuxt 的实验性功能。
::

## extends

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

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

**参见**：[`c12` 关于从远程源扩展配置层的文档](https://github.com/unjs/c12#extending-config-layer-from-remote-sources)

**参见**：[`giget` 文档](https://github.com/unjs/giget)

## 扩展名

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

- **类型**：`数组`
- **默认值**

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

## 特性

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/features#features"}
进一步了解 Nuxt 的可选启用功能。
::

## 未来

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/features#features"}
进一步了解如何选择启用将在框架未来版本（可能是大版本）中成为默认值的新功能。
::

## 钩子

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

内部钩子使用冒号分隔命名（如 build:done）。
为了便于配置，你也可以在 `nuxt.config` 中以层级对象形式结构化钩子（如下示例）。

**示例**：

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

## 忽略

相比 `ignorePrefix` 更加灵活，`ignore` 数组内匹配到的所有 glob 模式文件将被构建时忽略。

- **类型**：`数组`
- **默认值**

```json
[
  "**/*.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 文档](https://github.com/kaelzhang/node-ignore)

**示例**：

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

## ignorePrefix

`app/pages/`、`app/layouts/`、`app/middleware/` 和 `public/` 目录下，文件名以此前缀开头的文件将在构建过程中被忽略。用于防止某些文件被处理或在构建应用时被服务。默认前缀为 `-`，会忽略所有以 `-` 开头的文件。

- **类型**：`字符串`
- **默认值：**`"-"`

## imports

配置 Nuxt 组件自动导入。

**参见**：[Nuxt 文档](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/composables)

### `dirs`

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

- **类型**：`数组`

**示例**：

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

### `global`

- **类型**：`布尔值`
- **默认值：**`false`

### `scan`

是否扫描你的 `app/composables/` 和 `app/utils/` 目录内的组合函数以供自动导入。Nuxt 或其他模块注册的自动导入（如 `vue` 或 `nuxt` 的导入）依然启用。

- **类型**：`布尔值`
- **默认值：**`true`。

## logLevel

构建日志的日志等级。

在 CI 环境或无 TTY 时默认为 `silent`。该选项将应用于 Vite（silent）及 webpack（none）。

- **类型**：`字符串`
- **默认值：**`"info"`

## 模块

模块是可以扩展核心功能并集成无限服务的 Nuxt 扩展。

每个模块可以是字符串（包名称或文件路径）、元组（模块名称和选项对象）或内联模块函数。  
Nuxt 首先尝试通过 Node 的 `require` 路径（`node_modules`）加载；如果使用了 `~~` 路径别名，则会从项目的 `rootDir` 解析。

- **类型**：`array`

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

**示例**：

```ts
export default defineNuxtConfig({
  modules: [
  // Use package name
    '@nuxt/scripts',
    // Relative to the project root
    '~~/custom-modules/awesome.js',
    // With options
    ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
    // Inline definition
    function () {},
  ],
})
```

## modulesDir

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

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

- **类型**：`数组`
- **默认值**

```json
[
  "/<rootDir>/node_modules"
]
```

**示例**：

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

## nitro

Nitro 的配置。

**参见**：[Nitro 配置文档](https://nitro.zhcndoc.com/config)

### `routeRules`

- **类型**：`对象`

### `runtimeConfig`

- **类型**：`对象`
- **默认值**

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

## 优化

构建时优化配置。

### `asyncTransforms`

传递给 `unctx` 中转换器的选项，用于在执行 `await` 后保持异步上下文。

#### `asyncFunctions`

- **类型**：`数组`
- **默认值**

```json
[
  "defineNuxtPlugin",
  "defineNuxtRouteMiddleware"
]
```

#### `objectDefinitions`

##### `defineNuxtComponent`

- **类型**：`数组`
- **默认值**

```json
[
  "asyncData",
  "setup"
]
```

##### `defineNuxtPlugin`

- **类型**：`数组`
- **默认值**

```json
[
  "setup"
]
```

##### `definePageMeta`

- **类型**：`数组`
- **默认值**

```json
[
  "middleware",
  "validate"
]
```

### `keyedComposables`

要注入 key 的函数。

当传递函数的参数数量少于 `argumentLength` 时，会插入一个额外的特定字符串作为最后一个参数。此 key 对 SSR 和客户端 hydration 是稳定的。你需要处理此额外 key。key 基于函数在文件中的位置唯一。

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/modules/recipes-basics#add-keyed-functions"}
进一步了解带 key 的函数。
::

- **类型**：`数组`
- **默认值**

```json
[
  {
    "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。

**示例**：

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

##### `client`

- **类型**：`对象`
- **默认值**

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

##### `server`

- **类型**：`对象`
- **默认值**

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

## 页面

是否启用 Nuxt 3 中的 vue-router 集成。如果未指定值，且你的源码目录下存在 `app/pages/`，则默认启用。

还可以传入 glob 模式或数组，限定仅扫描某些文件作为页面。

**示例**：

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

## plugins

Nuxt 应用插件数组。

插件可以是字符串（绝对或相对文件路径），如果以 `.client` 或 `.server` 结尾，则只会在相应环境加载。
也可以是包含 `src` 和 `mode` 的对象。

- **类型**：`数组`

::callout
**注意**：插件也会从 `~/plugins` 目录自动注册，这些插件无须在 `nuxt.config` 中列出，除非需要自定义加载顺序。插件按照其 src 路径去重。
::

**参见**：[`app/plugins/` 目录文档](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/plugins)

**示例**：

```ts
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 插件的排序策略。

- **类型**：`函数`

### `plugins`

配置 PostCSS 插件选项。

**参见**：[PostCSS 文档](https://postcss.org/)

#### `autoprefixer`

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

**参见**：[`autoprefixer`](https://github.com/postcss/autoprefixer)

#### `cssnano`

- **类型**：`对象`

**参见**：[`cssnano` 配置选项](https://cssnano.github.io/cssnano/docs/config-file/#configuration-options)。

## rootDir

定义你的应用根目录。

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

- **类型**：`字符串`
- **默认值：**`"/<rootDir>"`

## routeRules

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

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

**参见**：[Nitro 路由规则文档](https://nitro.zhcndoc.com/config#routerules)。

## 路由

### `选项`

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

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

**参见**：[Vue Router 文档](https://router.vuejs.org/api/interfaces/routeroptions)

#### `hashMode`

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

- **类型**：`布尔值`
- **默认值：**`false`

#### `scrollBehaviorType`

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

- **类型**：`字符串`
- **默认值：**`"auto"`

## runtimeConfig

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

此对象值仅可通过服务器端的 `useRuntimeConfig` 访问。
主要用于保存不暴露给前端的私有配置，如 API 密钥。
`public` 和 `app` 下的配置将暴露给前端。
环境变量会自动替换对应的值，如设置环境变量 `NUXT_API_KEY=my-api-key NUXT_PUBLIC_BASE_URL=/foo/` 将替换下面的对应值。

- **类型**：`对象`
- **默认值**

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

**示例**：

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

## server

Nuxt 服务器构建器配置。

### `builder`

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

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

`"nitro"` 和 `"vite"` 分别是 `@nuxt/nitro-server` 和 `@nuxt/vite-server` 的简写。后者是实验性的，仅使用 Vite 实现：当 `ssr: false` 时，它会生成静态 SPA；启用 SSR 时，它会根据 Nuxt SSR 渲染器构建服务器，其入口会导出符合 Web 标准的 `{ fetch }`（`.output/server/index.mjs` 会在其前面提供静态输出，`nuxt preview` 则会运行它）。所有依赖都会打包到输出中，因此无需 `node_modules` 即可部署。`nuxt generate` 会在构建结束时爬取该服务器并写入静态的 `.output/public`。它不包含服务器运行时，因此服务器路由、除 `prerender` 以外的路由规则、内联样式和服务器组件均不可用，并且需要服务器的模块将无法运行。

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

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

## serverDir

定义 Nuxt 应用服务器目录，该目录用于存储 Nitro 路由、中间件和插件。

相对路径会相对于你的 `rootDir` 进行解析。

- **类型**：`字符串`
- **默认值：**`"/<rootDir>/server"`

## serverHandlers

Nitro 服务器处理器。

每个处理器接收选项：
- handler：定义处理器的文件路径。
- route：处理器对应的路由，遵循 [rou3](https://github.com/h3js/rou3) 约定。
- method：处理请求的 HTTP 方法。
- middleware：是否为中间件处理器。
- lazy：是否使用懒加载导入处理器。

- **类型**：`数组`

**参见**：[`server/` 目录文档](/docs/directory-structure/server)

::callout
**注意**：`server/api`、`server/middleware` 和 `server/routes` 中的文件会被 Nuxt 自动注册。
::

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

## sourcemap

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

若为单个布尔值，则同时应用于服务器和客户端。也支持 `'hidden'` 选项。
选项含义如下：
- `true`：生成源码映射并包含资源引用。
- `false`：不生成源码映射。
- `'hidden'`：生成源码映射但不包含资源引用。

- **类型**：`对象`
- **默认值**
```json
{
  "server": true,
  "client": false
}
~~~

## spaLoadingTemplate

布尔值或 HTML 文件路径。其内容会插入到任何使用 `ssr: false` 渲染的 HTML 页面中。

- 若未设置，如果某个层的 `app/` 目录中存在 `spa-loading-template.html` 文件，则使用该文件。
- 若为 `false`，不加载 SPA 加载指示器。
- 若为 `true`，Nuxt 会查找某个层的 `app/` 目录中的 `spa-loading-template.html` 文件，否则使用默认 Nuxt 图片。
- 若为路径，则相对于 `srcDir` 解析。
推荐的加载动画资源有 [SpinKit](https://github.com/tobiasahlin/SpinKit) 或 [SVG Spinners](https://icones.js.org/collection/svg-spinners)。
- **默认值：**`null`

**示例**：app/spa-loading-template.html

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

- **类型**：`字符串`
- **默认值**：`"app"`（Nuxt 4）、`"."`（兼容模式 3 的 Nuxt 3）

**示例**：

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

预期目录结构示例：

```bash
-| 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`，生成页面将无内容。

- **类型**：`布尔值`
- **默认值**：`true`。

## telemetry

手动禁用 Nuxt 远程统计。

**参见**：[Nuxt Telemetry](https://github.com/nuxt/telemetry) 获取更多。

## 测试

是否处于单元测试环境。

- **类型**：`布尔值`
- **默认值**：`false`。

## 主题

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

值应为指向源目录或相对当前配置的配置路径的字符串。
支持 `github:`、`gitlab:`、`bitbucket:` 或 `https://` 作为远程 Git 仓库。

- **类型**：`字符串`。

## TypeScript

Nuxt TypeScript 集成配置。

### `appTsConfig`

你可以通过此选项扩展生成的 `.nuxt/tsconfig.app.json`（以及旧版 `.nuxt/tsconfig.json`）TypeScript 配置。此处设置的选项优先于 `tsConfig`。

**参见**：[tsconfig.json 信息](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig)

### `builder`

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

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

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

- **默认值**：`null`

### `hoist`

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

- **类型**：`数组`
- **默认值**

```json
[
  "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 项目中。主要为主题和模块作者设计。

- **类型**：`布尔值`
- **默认值**：`false`

### `nodeTsConfig`

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

**参见**：[tsconfig.json 信息](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig)

### `serverTsConfig`

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

**参见**：[tsconfig.json 信息](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig)

### `sharedTsConfig`

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

**参见**：[tsconfig.json 信息](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig)

### `shim`

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

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

- **类型**：`布尔值`
- **默认值**：`false`

### `strict`

TypeScript 提供的更严格安全检查。转换完项目后，可以启用以获得更高的安全性。
[详见](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks)

- **类型**：`布尔值`
- **默认值**：`true`

<!-- @case-police-ignore tsConfig -->

### `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 信息](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig)

### `typeCheck`

启用构建时类型检查。

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

- **类型**：`布尔值`
- **默认值**：`false`

**参见**：[Nuxt TypeScript 文档](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/typescript)

## typesDir

定义生成的类型和 `tsconfig.json` 文件的存放目录。

默认使用 `buildDir`，并与其分开，这样即使 Nuxt 在其他位置构建（例如构建一个已在开发模式下运行过的项目时），项目 `tsconfig.json` 引用的配置也会保留在原处。

如果指定的是相对路径，则该路径相对于 `rootDir`。

- **类型**：`字符串`
- **默认值：**`"/<rootDir>/.nuxt"`

## unhead

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

### `legacy`

启用 `unhead` 模块的旧版兼容模式。包括：

- 禁用 Capo.js 排序
- 添加 `DeprecationsPlugin`：支持 `hid`、`vmid`、`children`、`body`
- 添加 `PromisesPlugin`：支持将 Promise 作为输入
- **类型**：`布尔值`
- **默认值**：`false`

**参见**：[unhead 迁移文档](https://unhead.unjs.io/docs/typescript/head/guides/get-started/migration)

**示例**：

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

### `renderSSRHeadOptions`

传递给 `renderSSRHead` 的用于定制输出的对象。

- **类型**：`对象`
- **默认值**

```json
{
  "omitLineBreaks": false
}
```

**示例**：

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

## vite

直接传递给 Vite 的配置。

顶层 `vite` 选项会在客户端和服务端环境中共享。使用 `$client` 和 `$server` 提供特定于环境的配置，这些配置会分别合并到对应构建中。

**示例**：

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

**参见**：[Vite 配置文档](https://vite.dev/config/) 获取更多信息。
请注意，并非所有 vite 选项都受 Nuxt 支持。

### `$client`

将会合并到 Vite 客户端（浏览器）构建配置中的设置。

- **类型**：`对象`

### `$server`

将会合并到 Vite 服务端构建配置中的设置。

- **类型**：`对象`

### `build`

#### `assetsDir`

- **类型**：`字符串`
- **默认值**：`"_nuxt/"`

#### `emptyOutDir`

- **类型**：`布尔值`
- **默认值**：`false`

### `cacheDir`

- **类型**：`字符串`
- **默认值**：`"/<rootDir>/node_modules/.cache/vite"`

### `clearScreen`

- **类型**：`布尔值`
- **默认值**：`true`

### `define`

- **类型**：`对象`
- **默认值**

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

### `esbuild`

- **类型**：`对象`
- **默认值**

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

### `mode`

- **类型**：`字符串`
- **默认值**：`"production"`

### `optimizeDeps`

#### `esbuildOptions`

- **类型**：`对象`
- **默认值**

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

#### `exclude`

- **类型**：`数组`
- **默认值**

```json
[
  "vue-demi"
]
```

### `publicDir`

### `resolve`

#### `extensions`

- **类型**：`数组`
- **默认值**

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

### `root`

- **类型**：`字符串`
- **默认值**：`"/<rootDir>"`

### `server`

#### `fs`

##### `allow`

- **类型**：`数组`
- **默认值**

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

### `vue`

#### `features`

##### `propsDestructure`

- **类型**：`布尔值`
- **默认值**：`true`

#### `isProduction`

- **类型**：`布尔值`
- **默认值**：`true`

#### `script`

##### `hoistStatic`

#### `template`

##### `compilerOptions`

- **类型**：`对象`

##### `transformAssetUrls`

- **类型**：`对象`
- **默认值**

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

### `vueJsx`

- **类型**：`对象`
- **默认值**

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

## vue

Vue.js 配置

### `compilerOptions`

构建时传递给 Vue 编译器的选项。

**参见**：[Vue 文档](https://vue.zhcndoc.com/api/application#app-config-compileroptions)

### `config`

可全局配置 Vue 应用。`nuxt.config` 中仅允许序列化选项，其他选项建议在运行时通过 Nuxt 插件设置。

**参见**：[Vue 应用配置文档](https://vue.zhcndoc.com/api/application#app-config)

### `propsDestructure`

启用 `defineProps` 的响应式解构。

- **类型**：`布尔值`
- **默认值**：`true`

### `runtimeCompiler`

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

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

- **类型**：`布尔值`
- **默认值**：`false`

::warning
运行时模板编译会将编译后的模板作为 JavaScript 执行。切勿编译来自用户提供或其他不受信任输入的模板；这样做等同于 `eval`，并可能导致跨站脚本攻击或远程代码执行。请参见 [Vue 安全指南](https://vuejs.org/guide/best-practices/security.html)。
::

### `transformAssetUrls`

#### `image`

- **类型**：`数组`
- **默认值**

```json
[
  "xlink:href",
  "href"
]
```

#### `img`

- **类型**：`数组`
- **默认值**

```json
[
  "src"
]
```

#### `source`

- **类型**：`数组`
- **默认值**

```json
[
  "src"
]
```

#### `use`

- **类型**：`数组`
- **默认值**

```json
[
  "xlink:href",
  "href"
]
```

#### `video`

- **类型**：`数组`
- **默认值**

```json
[
  "src",
  "poster"
]
```

## watch

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

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

- **类型**：`数组`。

## 监视器

覆盖 `nuxt.config` 中 watchers 配置。

### `chokidar`

传递给 `chokidar` 的选项。

**参见**：[chokidar](https://github.com/paulmillr/chokidar#api)

#### `ignoreInitial`

- **类型**：`布尔值`
- **默认值**：`true`

#### `ignorePermissionErrors`

- **类型**：`布尔值`
- **默认值**：`true`

### `rewatchOnRawEvents`

监听这些事件时，watcher 将重启。

### `webpack`

传递给 webpack 的 `watchOptions`。

**参见**：[webpack@4 监听选项](https://v4.webpack.js.org/configuration/watch/#watchoptions)。

#### `aggregateTimeout`

- **类型**：`数字`
- **默认值**：`1000`。

## webpack

### `aggressiveCodeRemoval`

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

- **类型**：`布尔值`
- **默认值**：`false`

### `analyze`

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

- **类型**：`对象`
- **默认值**

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

**示例**：

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

### `cssSourceMap`

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

- **类型**：`布尔值`
- **默认值**：`false`

### `devMiddleware`

配置详见[webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware)。

#### `stats`

- **类型**：`字符串`
- **默认值**：`"none"`

### `experiments`

配置[webpack 实验特性](https://webpack.js.org/configuration/experiments/)

### `extractCSS`

启用公共 CSS 提取。

基于 [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin)，CSS 通常会被分离到每个组件对应文件。支持独立缓存 CSS 与 JS。

- **类型**：`布尔值`
- **默认值**：`true`

**示例**：

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

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

**示例**：

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

### `filenames`

自定义构建文件名。

为更好理解清单用法，查看[webpack 文档](https://webpack.js.org/guides/code-splitting/)。

::callout
**注意**：生产环境使用非哈希命名需谨慎，浏览器可能缓存资源，导致更新后首载不生效。
::

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

**示例**：

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

#### `app`

- **类型**：`函数`

#### `chunk`

- **类型**：`函数`

#### `css`

- **类型**：`函数`

#### `font`

- **类型**：`函数`

#### `img`

- **类型**：`函数`

#### `video`

- **类型**：`函数`

### `friendlyErrors`

设置为 `false` 可停止在开发期间向终端输出客户端构建错误。

- **类型**：`布尔值`
- **默认值**：`true`

### `hotMiddleware`

配置详见 [webpack-hot-middleware](https://github.com/webpack/webpack-hot-middleware)

### `loaders`

自定义 Nuxt 内置 webpack loaders 的选项。

#### `css`

详见 [css-loader](https://github.com/webpack/css-loader)

##### `esModule`

- **类型**：`布尔值`
- **默认值**：`false`

##### `importLoaders`

- **类型**：`数字`
- **默认值**：`0`

##### `url`

###### `filter`

- **类型**：`函数`

#### `cssModules`

详见 [css-loader](https://github.com/webpack/css-loader)

##### `esModule`

- **类型**：`布尔值`
- **默认值**：`false`

##### `importLoaders`

- **类型**：`数字`
- **默认值**：`0`

##### `modules`

###### `localIdentName`

- **类型**：`字符串`
- **默认值**：`"[local]_[hash:base64:5]"`

##### `url`

###### `filter`

- **类型**：`函数`

#### `esbuild`

- **类型**：`对象`
- **默认值**

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

**参见**：[esbuild loader](https://github.com/privatenumber/esbuild-loader)

#### `file`

**参见**：[`file-loader` 选项](https://github.com/webpack/file-loader#options)

**默认值**：

```json
{ "esModule": false }
```

##### `esModule`

- **类型**：`布尔值`
- **默认值**：`false`

##### `limit`

- **类型**：`数字`
- **默认值**：`1000`

#### `fontUrl`

**参见**：[`file-loader` 选项](https://github.com/webpack/file-loader#options)

**默认值**：

```json
{ "esModule": false }
```

##### `esModule`

- **类型**：`布尔值`
- **默认值**：`false`

##### `limit`

- **类型**：`数字`
- **默认值**：`1000`

#### `imgUrl`

**参见**：[`file-loader` 选项](https://github.com/webpack/file-loader#options)

**默认值**：

```json
{ "esModule": false }
```

##### `esModule`

- **类型**：`布尔值`
- **默认值**：`false`

##### `limit`

- **类型**：`数字`
- **默认值**：`1000`

#### `less`

- **默认值**

```json
{
  "sourceMap": false
}
```

**参见**：[`less-loader` 选项](https://github.com/webpack/less-loader#options)

#### `pugPlain`

**参见**：[`pug` 选项](https://pugjs.org/api/reference.html#options)

#### `sass`

**参见**：[`sass-loader` 选项](https://github.com/webpack/sass-loader#options)

**默认值**：

```json
{
  "sassOptions": {
    "indentedSyntax": true
  }
}
```

##### `sassOptions`

###### `indentedSyntax`

- **类型**：`布尔值`
- **默认值**：`true`

#### `scss`

- **默认值**

```json
{
  "sourceMap": false
}
```

**参见**：[`sass-loader` 选项](https://github.com/webpack/sass-loader#options)

#### `stylus`

- **默认值**

```json
{
  "sourceMap": false
}
```

**参见**：[`stylus-loader` 选项](https://github.com/webpack/stylus-loader#options)

#### `vue`

详见 [vue-loader](https://github.com/vuejs/vue-loader)

##### `compilerOptions`

- **类型**：`对象`

##### `propsDestructure`

- **类型**：`布尔值`
- **默认值**：`true`

##### `transformAssetUrls`

- **类型**：`对象`
- **默认值**

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

#### `vueStyle`

- **默认值**

```json
{
  "sourceMap": false
}
```

### `optimization`

配置[webpack 优化](https://webpack.js.org/configuration/optimization/)

#### `minimize`

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

- **类型**：`布尔值`
- **默认值**：`true`

#### `minimizer`

可自定义最小化插件数组。

#### `runtimeChunk`

- **类型**：`字符串`
- **默认值**：`"single"`

#### `splitChunks`

##### `automaticNameDelimiter`

- **类型**：`字符串`
- **默认值**：`"/"`

##### `cacheGroups`

##### `chunks`

- **类型**：`字符串`
- **默认值**：`"all"`

### `optimizeCSS`

OptimizeCSSAssets 插件的选项。

当 `extractCSS` 启用时默认为 true。

- **类型**：`布尔值`
- **默认值**：`false`

**参见**：[css-minimizer-webpack-plugin 文档](https://github.com/webpack/css-minimizer-webpack-plugin)。

### `plugins`

添加 webpack 插件。

- **类型**：`数组`

**示例**：

```ts
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` 选项](https://github.com/webpack/postcss-loader#options)

#### `postcssOptions`

##### `plugins`

- **类型**：`对象`
- **默认值**

```json
{
  "autoprefixer": {},
  "cssnano": {}
}
```

### `profile`

启用 webpackbar 性能分析器。

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

- **类型**：`布尔值`
- **默认值**：`false`

**参见**：[webpackbar](https://github.com/unjs/webpackbar#profile)。

### `serverURLPolyfill`

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

默认为 `'url'`（[参考包](https://www.npmjs.com/package/url)）。

- **类型**：`字符串`
- **默认值**：`"url"`

### `warningIgnoreFilters`

过滤构建时忽略的警告。

- **类型**：`数组`

## workspaceDir

定义应用的工作区目录。

通常用于 monorepo 场景。Nuxt 会尝试自动检测工作目录，但你可以在这里覆盖它。通常不需要配置。

- **类型**：`字符串`
- **默认值**：\`"/


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.