# 配置

:read-more{to="/docs/configuration"}

::note
本页中的所有示例都假设在 `nitro.config.ts` 中导入了以下内容：

```ts
import { defineConfig } from "nitro";
```
::

## 常规

预设、日志记录和运行时配置的核心选项。

### `preset`

用于**生产环境**构建的部署预设。也可以通过 `NITRO_PRESET` 环境变量设置。

开发模式的预设始终为 `nitro_dev`。生产环境的默认预设为 `node_server`，它会构建一个独立的 Node.js 服务器。

如果未设置 `preset` 选项，且 Nitro 正在已知环境中运行，则会自动检测预设。

```ts
export default defineConfig({
  preset: "cloudflare_pages", // 部署到 Cloudflare Pages
});
```

### `defaultPreset`

自定义在未设置 `preset` 且未自动检测到任何已知托管提供商时使用的**回退**预设。

默认情况下，Nitro 会回退到基于运行时的预设（在这些运行时上运行时，使用 `node`，以及 `deno` 或 `bun`）。显式指定的 `preset`、`NITRO_PRESET` 环境变量，以及自动检测到的提供商（Vercel、Netlify、Cloudflare Pages 等）都优先于 `defaultPreset`。

它接受一个预设名称或内联预设定义。

```ts
export default defineConfig({
  defaultPreset: "node_cluster", // 默认使用 node_cluster 而不是 node_server
});
```

### `debug`

- 默认值：`false`{lang=ts}（当设置了 `DEBUG` 环境变量时为 `true`{lang=ts}）

启用调试模式以输出详细日志和额外的开发信息。

```ts
export default defineConfig({
  debug: true,
});
```

### `logLevel`

- 默认值：`3`{lang=ts}（检测到测试环境时为 `1`{lang=ts}）

日志详细程度级别。更多信息请参见 [consola](https://github.com/unjs/consola?tab=readme-ov-file#log-level)。

```ts
export default defineConfig({
  logLevel: 4, // 详细日志
});
```

### `runtimeConfig`

- 默认值：`{ app: {}, nitro: {} }`{lang=ts}

服务器运行时配置。Nitro 会将 `app.baseURL`（来自 [`baseURL`](#baseurl) 选项）注入 `app` 命名空间。

**注意：** `app` 和 `nitro` 命名空间保留供内部使用。

```ts
export default defineConfig({
  runtimeConfig: {
    apiSecret: "default-secret", // 使用 NITRO_API_SECRET 覆盖
  },
});
```

### `compatibilityDate`

- 未提供时的默认行为：`"latest"`{lang=ts}

部署提供商会引入 Nitro 预设可以利用的新功能，但其中一些功能需要显式启用。请将此项设置为你已测试过的最新日期，格式为 `YYYY-MM-DD`，以利用最新的预设功能。

```ts
export default defineConfig({
  compatibilityDate: "2025-01-01",
});
```

### `static`

- 默认值：`false`{lang=ts}

启用静态站点生成模式。

```ts
export default defineConfig({
  static: true, // 预渲染所有路由
});
```

## 功能特性

启用和配置 Nitro 的内置功能，例如存储、任务和资源。

### `features`

- 默认值：`{}`{lang=ts}

启用内置功能。

#### `runtimeHooks`

- 默认值：自动检测（如果至少有一个 nitro 插件则启用）

启用请求和响应的运行时钩子。

#### `websocket`

- 默认值：`false`{lang=ts}

启用 WebSocket 支持。

```ts
export default defineConfig({
  features: {
    runtimeHooks: true,
    websocket: true, // 启用 WebSocket 支持
  },
});
```

:read-more{to="/docs/websocket"}

### `experimental`

- 默认值：`{}`{lang=ts}

启用实验性功能。

#### `openAPI`

- 默认值：`false`{lang=ts}

启用 `/_scalar`、`/_swagger` 和 `/_openapi.json` 端点。

::note
建议优先使用顶级的 [`openAPI`](#openAPI) 选项进行配置。
::

#### `typescriptBundlerResolution`

启用 TypeScript 打包器模块解析。参见 [TypeScript#51669](https://github.com/microsoft/TypeScript/pull/51669)。

::note
此标志目前不起作用：`nitro/tsconfig` 和生成的 tsconfig 始终使用打包器模块解析。
::

#### `asyncContext`

为 `useRequest()` 启用原生异步上下文支持。

#### `sourcemapMinify`

设置为 `false` 可禁用实验性的 source map 压缩（默认在启用 `sourcemap` 时开启）。

#### `envExpansion`

允许在运行时配置中展开环境变量。参见[配置指南](/docs/configuration#env-expansion)和 [#2043](https://github.com/nitrojs/nitro/pull/2043)。

#### `database`

启用实验性数据库支持。参见[数据库](/docs/database)。

#### `tasks`

启用实验性任务支持。参见[任务](/docs/tasks)。

#### `tracingLogger`

使用内置的无依赖遥测接收器，将 Nitro 跟踪通道的 span 记录到控制台；该接收器会记录每个已完成的 span（h3、srvx、unstorage，……）。需要启用 [`tracingChannel`](#tracingchannel)。

```ts
export default defineConfig({
  experimental: {
    typescriptBundlerResolution: true,
    asyncContext: true,
    envExpansion: true,
    database: true,
    tasks: true,
  },
});
```

### `openAPI`

顶级 OpenAPI 配置。

你可以传递一个对象来修改你的 OpenAPI 规范：

```js
openAPI: {
  meta: {
    title: '我的超棒项目',
    description: '这可能会成为下一个重大项目。',
    version: '1.0'
  }
}
```

默认情况下，这些路由在生产环境中是禁用的。要启用它们，请使用 `production` 键。
`"runtime"` 允许中间件使用，而 `"prerender"` 是最有效的，因为 JSON 响应是恒定的。

```js
openAPI: {
    // 重要：如有必要，确保保护 OpenAPI 路由！
    production: "runtime", // 或 "prerender"
}
```

要自定义 Scalar 集成，[传入配置对象](https://github.com/scalar/scalar)，例如：

```js
openAPI: {
  ui: {
    scalar: {
      theme: 'purple'
    }
  }
}
```

要自定义 Swagger UI，请传入任意 [Swagger UI 配置选项](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)：

```js
openAPI: {
  ui: {
    swagger: {
      persistAuthorization: true,
      deepLinking: true,
      docExpansion: 'none',
      filter: true,
    }
  }
}
```

要自定义端点：

```js
openAPI: {
  route: "/_docs/openapi.json",
  ui: {
    scalar: {
      route: "/_docs/scalar"
    },
    swagger: {
      route: "/_docs/swagger"
    }
  }
}
```

:read-more{to="/docs/openapi"}

### `future`

- 默认值：`{}`{lang=ts}

等待在主要版本中发布的新功能，以避免破坏性变更。

#### `nativeSWR`

对 Netlify 和 Vercel 预设使用内置的 SWR 功能（使用缓存层和存储），而不是回退到 ISR 行为。

```ts
export default defineConfig({
  future: {
    nativeSWR: true,
  },
});
```

### `kv`

- 默认值：`{}`{lang=ts}

KV 存储配置。

```ts
export default defineConfig({
  kv: {
    redis: {
      driver: "redis",
      url: "redis://localhost:6379",
    },
  },
});
```

使用 `$development` 键覆盖开发期间的挂载配置：

```ts
export default defineConfig({
  $development: {
    kv: {
      redis: {
        driver: "fs",
        base: "./data/redis", // 在开发环境中使用文件系统
      },
    },
  },
});
```

`$development` 仅适用于开发服务器。使用 `$prerender` 可在预渲染时覆盖挂载配置。具有不同 `driver` 的挂载会替换整个挂载；具有相同 `driver` 的挂载则会对其选项进行深度合并。

::note
以前名为 `storage`，现仍可作为已弃用的别名使用。已弃用的 `devStorage` 选项由 `$development`（以及 `$prerender`）中的 `kv` 替代。
::

:read-more{to="/docs/storage"}

### `database`

数据库连接配置。需要 `experimental.database: true`。

```ts
export default defineConfig({
  database: {
    default: {
      connector: "sqlite",
      options: { name: "db" },
    },
  },
});
```

:read-more{to="/docs/database"}

### `devDatabase`

开发模式的数据库连接配置覆盖。

```ts
export default defineConfig({
  devDatabase: {
    default: {
      connector: "sqlite",
      options: { name: "db-dev" }, // 独立的开发数据库
    },
  },
});
```

### `renderer`

- 类型：`false`{lang=ts} | `{ handler?: string, static?: boolean, template?: string }`{lang=ts}

指向主渲染入口（文件应将事件处理器作为默认导出）。

```ts
export default defineConfig({
  renderer: {
    handler: "~/renderer", // 渲染处理器的路径
  },
});
```

:read-more{to="/docs/renderer"}

### `ssrRoutes`

应进行服务器端渲染的路由。

```ts
export default defineConfig({
  ssrRoutes: ["/app/**"],
});
```

### `serveStatic`

- 类型：`boolean`{lang=ts} | `'node'`{lang=ts} | `'inline'`{lang=ts}
- 默认值：取决于所用的部署预设。

在生产环境中提供 `public/` 资源服务。

**注意：** 强烈建议让你的边缘 CDN（Nginx、Apache、Cloud）直接提供 `.output/public/` 目录服务，以启用压缩和更高级别的缓存。

```ts
export default defineConfig({
  serveStatic: "node", // 使用 Node.js 提供静态资源服务
});
```

### `noPublicDir`

- 默认值：`false`{lang=ts}

如果启用，将禁用 `.output/public` 目录的创建。跳过复制 `public/` 目录，同时禁用预渲染。

```ts
export default defineConfig({
  noPublicDir: true, // 跳过 public 目录输出
});
```

### `publicAssets`

在开发中提供、在生产中打包的公共资源目录。

如果检测到 `public/` 目录，它将被默认添加，但你也可以自己添加更多！

可以使用 `maxAge` 选项为资源设置 Cache-Control 标头：

```ts
export default defineConfig({
  publicAssets: [
    {
      baseURL: "images",
      dir: "public/images",
      maxAge: 60 * 60 * 24 * 7, // 7 天
    },
  ],
});
```

上述配置会在 `public/images/` 文件夹下的资源中生成以下响应头：

`cache-control: public, max-age=604800, immutable`

`dir` 选项是你的文件在文件系统中的位置；`baseURL` 选项是它们在提供服务/打包时可访问的文件夹路径。

:read-more{to="/docs/assets"}

### `compressPublicAssets`

- 类型：`boolean`{lang=ts} | `{ gzip?: boolean, brotli?: boolean, zstd?: boolean }`{lang=ts}
- 默认值：`false`{lang=ts}

如果启用，Nitro 将为大于 1024 字节的公共资源和预渲染路由生成预压缩版本（gzip、brotli 和/或 zstd）到公共目录中。使用默认压缩级别。使用此选项，你可以在不使用 CDN 的情况下支持零开销资源压缩。

```ts
export default defineConfig({
  compressPublicAssets: {
    gzip: true,
    brotli: true, // 启用 gzip 和 brotli 预压缩
  },
});
```

### `serverAssets`

服务器逻辑中可访问并在生产中打包的资源。

```ts
export default defineConfig({
  serverAssets: [
    {
      baseName: "templates",
      dir: "./templates", // 将 templates/ 作为服务器资源打包
    },
  ],
});
```

:read-more{to="/docs/assets#server-assets"}

### `modules`

- 默认值：`[]`{lang=ts}

Nitro 模块数组。模块可以是字符串（路径）、带有 `setup` 函数的模块对象，或函数。

```ts
export default defineConfig({
  modules: [
    "./modules/my-module.ts",
    (nitro) => {
      nitro.hooks.hook("compiled", () => { /* ... */ });
    },
  ],
});
```

### `plugins`

- 默认值：`[]`{lang=ts}

nitro 插件路径数组。它们会在首次初始化时按顺序执行。

注意，Nitro 会自动注册 `plugins/` 目录中的插件。

```ts
export default defineConfig({
  plugins: [
    "~/plugins/my-plugin.ts",
  ],
});
```

:read-more{to="/docs/plugins"}

### `tasks`

- 默认值：`{}`{lang=ts}

任务定义。每个键都是一个任务名称，可选配置 `handler` 路径和 `description`。

从 `<serverDir>/tasks/` 扫描到的任务只需在此处提供 `description`。`handler` 会按原样导入，不会根据项目根目录解析，因此必须是绝对路径或包名称。

```ts
import { fileURLToPath } from "node:url";

export default defineConfig({
  tasks: {
    "db:migrate": {
      description: "运行数据库迁移",
    },
    "db:seed": {
      handler: fileURLToPath(new URL("scripts/seed.ts", import.meta.url)),
      description: "为数据库填充数据",
    },
  },
});
```

:read-more{to="/docs/tasks"}

### `scheduledTasks`

- 默认值：`{}`{lang=ts}

cron 表达式到任务名称的映射。

```ts
export default defineConfig({
  scheduledTasks: {
    "0 * * * *": "cleanup:temp",
    "*/5 * * * *": ["health:check", "metrics:collect"],
  },
});
```

:read-more{to="/docs/tasks"}

### `virtual`

- 默认值：`{}`{lang=ts}

从动态虚拟导入名称到其内容或返回内容的（异步）函数的映射。

```ts
export default defineConfig({
  virtual: {
    "#config": `export default { version: "1.0.0" }`,
  },
});
```

### `ignore`

- 默认值：`[]`{lang=ts}

扫描目录时要忽略的全局模式数组。

```ts
export default defineConfig({
  ignore: [
    "routes/_legacy/**", // 跳过旧版路由处理器
  ],
});
```

### `wasm`

- 类型：`false`{lang=ts} | `UnwasmPluginOptions`{lang=ts}
- 默认值：`{}`{lang=ts}

WASM 支持配置。有关选项请参见 [unwasm](https://github.com/unjs/unwasm)。

```ts
export default defineConfig({
  wasm: {}, // 启用 WASM 导入支持
});
```

## 开发

仅影响开发服务器（`nitro dev`）的选项。

### `devServer`

- 默认值：`{ watch: [] }`{lang=ts}

开发服务器选项。你可以使用 `watch` 来让开发服务器在指定路径中的任何文件发生变化时重新加载。

支持 `port`、`hostname`、`watch` 和 `runner` 选项。

```ts
export default defineConfig({
  devServer: {
    port: 3001,
    watch: ["./server/plugins"],
  },
});
```

### `watchOptions`

开发模式的监听选项。更多信息请查看 [chokidar](https://github.com/paulmillr/chokidar)。

```ts
export default defineConfig({
  watchOptions: {
    ignored: ["**/node_modules/**", "**/dist/**"],
  },
});
```

### `devProxy`

开发服务器的代理配置。

你可以使用此选项来覆盖开发服务器路由并代理转发请求。

```ts
export default defineConfig({
  devProxy: {
    "/proxy/test": "http://localhost:3001",
    "/proxy/example": { target: "https://example.com", changeOrigin: true },
  },
});
```

查看 [httpxy](https://github.com/unjs/httpxy) 了解所有可用的目标选项。

## 日志

### `logging`

- 默认值：`{ compressedSizes: true, buildSuccess: true }`{lang=ts}

控制构建日志行为。将 `compressedSizes` 设置为 `false` 可跳过报告压缩后的包大小。将 `buildSuccess` 设置为 `false` 可隐藏构建成功消息。

```ts
export default defineConfig({
  logging: {
    compressedSizes: false, // 跳过压缩大小报告
    buildSuccess: false,
  },
});
```

## 路由

用于定义路由、处理程序和路由级行为的选项。

### `baseURL`

- 默认值：`"/"`{lang=ts}（如果提供，则使用 `NITRO_APP_BASE_URL` 环境变量）

服务器的主基础 URL。

```ts
export default defineConfig({
  baseURL: "/app/", // 在 /app/ 前缀下提供应用
});
```

### `apiBaseURL`

- 默认值：`"/api"`{lang=ts}

更改默认的 API 基础 URL 前缀。

```ts
export default defineConfig({
  apiBaseURL: "/server/api", // /server/api/ 下的 API 路由
});
```

### `serverEntry`

- 类型：`false`{lang=ts} | `string`{lang=ts} | `{ handler: string, format?: EventHandlerFormat }`{lang=ts}

自定义服务器入口点配置。设置为 `false` 可禁用默认服务器入口。

```ts
export default defineConfig({
  serverEntry: "./server.ts",
});
```

:read-more{to="/docs/server-entry"}

### `handlers`

服务器处理程序和路由。

如果服务器目录内存在 `routes/`、`api/` 或 `middleware/` 目录，它们将自动添加到 handlers 数组中。

```ts
export default defineConfig({
  handlers: [
    { route: "/health", handler: "./handlers/health.ts" },
    { route: "/admin/**", handler: "./handlers/admin.ts", method: "get" },
  ],
});
```

:read-more{to="/docs/routing"}

### `devHandlers`

以程序化实例而非文件路径形式提供的处理程序。与常规的 [`handlers`](#handlers) 不同，后者由打包器导入和转换，而 `devHandlers` 接受直接传入的处理程序函数。

**注意：** 它们**仅在开发模式下可用**，**不会包含在生产构建中**。

```ts
export default defineConfig({
  devHandlers: [
    { route: "/__dev", handler: defineHandler(() => "仅开发环境路由") },
  ],
});
```

### `routes`

- 默认值：`{}`{lang=ts}

内联路由定义。从路由模式到处理程序路径或处理程序选项的映射。

```ts
export default defineConfig({
  routes: {
    "/hello": "./routes/hello.ts",
    "/greet": { handler: "./routes/greet.ts", method: "post" },
  },
});
```

### `errorHandler`

- 类型：`string`{lang=ts} | `string[]`{lang=ts}

自定义运行时错误处理程序的路径。替换 nitro 内置的错误页面。

```ts [nitro.config.ts]
import { defineConfig } from "nitro";

export default defineConfig({
  errorHandler: "~/error",
});
```

```ts [error.ts]
import { defineErrorHandler } from "nitro";

export default defineErrorHandler((error, event) => {
  return new Response('[自定义错误处理程序] ' + error.stack, {
    headers: { 'Content-Type': 'text/plain' }
  });
});
```

### `routeRules`

**🧪 实验性功能！**

路由选项。它是从路由模式（遵循 [rou3](https://github.com/h3js/rou3)）到路由选项的映射。

当设置了 `cache` 选项时，匹配该模式的处理程序将自动用 `defineCachedHandler` 包装。

查看[缓存 API](/docs/cache)了解所有可用的缓存选项。

::note
`swr: true|number` 是 `cache: { swr: true, maxAge: number }` 的快捷方式
::

```js
routeRules: {
  '/blog/**': { swr: true },
  '/feed/**': { swr: 600 },
  '/docs/**': { static: true },
  '/dashboard/**': { cache: { /* cache options*/ } },
  '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
  '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
  '/old-page': { redirect: '/new-page' }, // 使用状态码 307（临时重定向）
  '/old-page2': { redirect: { to:'/new-page2', statusCode: 301 } },
  '/old-page/**': { redirect: '/new-page/**' },
  '/proxy/example': { proxy: 'https://example.com' },
  '/proxy/**': { proxy: '/api/**' },
}
```

:read-more{to="/docs/routing#route-rules"}

### `prerender`

预渲染选项。指定的任何路由都会在构建期间被获取，并作为静态资源复制到 `.output/public` 目录。

默认值：

```ts
{
  autoSubfolderIndex: true,
  concurrency: 1,
  interval: 0,
  failOnError: false,
  crawlLinks: false,
  ignore: [],
  routes: [],
  retry: 3,
  retryDelay: 500
}
```

以 `ignore` 中列出的前缀开头，或匹配正则表达式或函数的任何路由（字符串）都会被忽略。

如果将 `crawlLinks` 选项设置为 `true`，nitro 默认从 `/` 开始（或从 `routes` 数组中的所有路由开始），从 HTML 页面中提取 `<a>` 标签，并对这些页面也进行预渲染。

你可以将 `failOnError` 选项设置为 `true`，以便在 Nitro 无法预渲染某个路由时停止 CI。

`interval` 和 `concurrency` 选项允许你控制预渲染速度，这有助于在调用外部 API 时避免触发速率限制。

`autoSubfolderIndex` 选项控制如何在 `.output/public` 目录中生成文件：

```bash
# autoSubfolderIndex: true（默认）
/about -> .output/public/about/index.html
# autoSubfolderIndex: false
/about -> .output/public/about.html
```

当你的托管提供商无法提供关于尾部斜杠的选项时，此选项很有用。

预渲染器将尝试以 500ms 的延迟渲染页面 3 次。使用 `retry` 和 `retryDelay` 来更改此行为。

将 `ignoreUnprefixedPublicAssets` 设置为 `true`，可跳过没有基础 URL 前缀的公共资源的预渲染。

## 目录

自定义 Nitro 查找源文件和写入输出文件的位置。

### `workspaceDir`

项目工作空间根目录。

未设置 `workspaceDir` 选项时，会自动检测工作空间目录（例如 pnpm 工作空间）。

```ts
export default defineConfig({
  workspaceDir: "../", // monorepo 根目录
});
```

### `rootDir`

项目主目录。

```ts
export default defineConfig({
  rootDir: "./src/server",
});
```

### `serverDir`

- 类型：`boolean`{lang=ts} | `"./"`{lang=ts} | `"./server"`{lang=ts} | `string`{lang=ts}
- 默认值：`false`{lang=ts}

用于扫描 `api/`、`routes/`、`plugins/`、`utils/`、`middleware/`、`modules/` 和 `tasks/` 文件夹的服务器目录。

设置为 `false` 时，禁用自动目录扫描。设置为 `"./"` 以使用根目录，或设置为 `"./server"` 以使用 `server/` 子目录。

```ts
export default defineConfig({
  serverDir: "./server", // 扫描 `server/` 子目录
});
```

### `scanDirs`

- 默认值：`[]`{lang=ts}（为空时会扫描服务器源目录）

要扫描并自动注册文件的目录列表，例如 API 路由。

```ts
export default defineConfig({
  scanDirs: ["./modules/auth/api", "./modules/billing/api"],
});
```

### `apiDir`

- 默认值：`"api"`{lang=ts}

定义用于扫描 API 路由处理程序的不同目录。

```ts
export default defineConfig({
  apiDir: "endpoints", // 扫描 `endpoints/` 而不是 `api/`
});
```

### `routesDir`

- 默认值：`"routes"`{lang=ts}

定义用于扫描路由处理程序的不同目录。

```ts
export default defineConfig({
  routesDir: "pages", // 扫描 `pages/` 而不是 `routes/`
});
```

### `buildDir`

- 默认值：`"node_modules/.nitro"`{lang=ts}

Nitro 用于生成构建相关文件的临时工作目录。

```ts
export default defineConfig({
  buildDir: ".nitro", // 在项目根目录中使用 `.nitro/`
});
```

### `output`

- 默认值：`{ dir: '.output', serverDir: '.output/server', publicDir: '.output/public' }`{lang=ts}

生产包的输出目录。

```ts
export default defineConfig({
  output: {
    dir: "dist",
    serverDir: "dist/server",
    publicDir: "dist/public",
  },
});
```

## 构建

打包工具选择和构建输出调整。

### `builder`

- 类型：`"rollup"`{lang=ts} | `"rolldown"`{lang=ts} | `"vite"`{lang=ts}
- 默认值：`undefined`{lang=ts}（自动检测）

指定用于构建的打包工具。

```ts
export default defineConfig({
  builder: "vite",
});
```

### `rollupConfig`

额外的 rollup 配置。

```ts
export default defineConfig({
  rollupConfig: {
    output: { manualChunks: { vendor: ["lodash-es"] } },
  },
});
```

### `rolldownConfig`

额外的 rolldown 配置。

```ts
export default defineConfig({
  rolldownConfig: {
    output: { banner: "/* 使用 nitro 构建 */" },
  },
});
```

### `vite`

`vite` 打包工具和 `nitro/vite` 插件的选项。

- `path`：要使用的 `vite` 包，可以是其目录或入口文件的路径或 `file://` URL。默认情况下，会从项目根目录解析 `vite`。以编程方式运行 Vite 的框架应传入自己的 `vite`（例如 `import.meta.resolve("vite")`），以便开发模块运行器与正在运行的实例保持一致。

```ts
export default defineConfig({
  vite: {
    path: import.meta.resolve("vite"),
  },
});
```

### `entry`

打包工具的入口点。

```ts
export default defineConfig({
  entry: "./server/entry.ts", // 自定义入口文件
});
```

### `unenv`

用于环境兼容性的 [unenv](https://github.com/unjs/unenv/) 预设。

```ts
export default defineConfig({
  unenv: {
    alias: { "my-module": "my-module/web" },
  },
});
```

### `alias`

模块解析的路径别名。

```ts
export default defineConfig({
  alias: {
    "~utils": "./src/utils",
    "#shared": "./shared",
  },
});
```

### `minify`

- 默认值：`false`{lang=ts}

压缩打包文件。

某些预设（尤其是 worker 运行时）默认启用压缩。在调试生产环境、worker 或边缘构建时，将 `minify: false` 设置为 `false`，以便保持堆栈跟踪易于阅读。

```ts
export default defineConfig({
  minify: true, // 压缩生产包
});
```

```ts
export default defineConfig({
  minify: false, // 更方便地调试 worker／边缘程序包
});
```

### `inlineDynamicImports`

- 默认值：`false`{lang=ts}

将所有代码打包到单个文件中，而不是为每个路由创建单独的块。

当为 `false` 时，每个路由处理程序都成为一个按需加载的独立块。当为 `true` 时，所有内容都打包在一起。某些预设默认启用此选项。

```ts
export default defineConfig({
  inlineDynamicImports: true, // 单个输出文件
});
```

### `sourcemap`

- 默认值：`false`{lang=ts}

启用 source map 生成。查看[选项](https://rollupjs.org/configuration-options/#output-sourcemap)。

```ts
export default defineConfig({
  sourcemap: true, // 生成 `.map` 文件
});
```

### `node`

- 默认值：`true`{lang=ts}

指定构建是否用于 Node.js。如果设置为 `false`，nitro 会尝试使用 [unenv](https://github.com/unjs/unenv) 模拟 Node.js 依赖并调整其行为。

```ts
export default defineConfig({
  node: false, // 面向非 Node.js 运行时
});
```

### `replace`

构建时的字符串替换。

```ts
export default defineConfig({
  replace: {
    "process.env.APP_VERSION": JSON.stringify("1.0.0"),
  },
});
```

### `commonJS`

指定 rollup CommonJS 插件的额外配置。

```ts
export default defineConfig({
  commonJS: {
    requireReturnsDefault: "auto",
  },
});
```

### `exportConditions`

模块解析的自定义导出条件。

```ts
export default defineConfig({
  exportConditions: ["worker", "production"],
});
```

### `noExternals`

- 默认值：`false`{lang=ts}

禁止将包外部化。外部化的包会在运行时导入，而不是打包进去，因此它们无法使用你的 `alias` 配置。

在生产构建中，Nitro 已经会打包几乎所有内容：只有原生包或其他无法打包的包，以及 [`traceDeps`](#tracedeps) 中列出的包会保留为外部依赖。在开发环境中，为了提高速度，`node_modules` 中的依赖会保留为外部依赖；此选项在这种情况下最为有用。

将其设为 `true`，可打包所有内容，包括通常保留为外部依赖的包：

```ts
export default defineConfig({
  noExternals: true, // 打包所有依赖项
});
```

#### 内联指定的包

传入数组，只内联部分模块。`RegExp` 条目按原样使用；字符串条目会经过转义，并按路径子字符串匹配。

每个模式都会与书写形式的导入说明符（例如 `@scope/my-lib`）以及解析后的绝对文件路径（例如 `/…/node_modules/@scope/my-lib/dist/index.mjs`）进行匹配。任一匹配成功都会使模块保持打包状态，因此通常只需提供包名称即可：

```ts
export default defineConfig({
  alias: {
    "@shared": "./shared",
  },
  noExternals: ["@scope/my-lib"],
});
```

如果需要更精确的匹配，例如在 monorepo 中内联一个包，同时避免匹配名称相似的其他包，请使用路径模式：

```ts
export default defineConfig({
  noExternals: [/packages[\\/]my-lib/],
});
```

在此类模式中使用 `[\\/]` 而不是 `/`，以便也能匹配 Windows 路径。

::note
在 Nitro 2 中，此选项名为 `externals.inline`。
::

### `traceDeps`

- 默认值：`[]`{lang=ts}

要跟踪并包含在构建输出中的额外依赖项。

支持特殊前缀：
- `!pkg`：从追踪中排除内置包。
- `pkg*`：完整追踪，复制包的所有文件，而不仅是追踪到的文件。

```ts
export default defineConfig({
  traceDeps: [
    "sharp",
    "better-sqlite3",
    "my-pkg*", // 完整追踪（复制所有包文件）
    "!unwanted-pkg", // 从追踪中排除
  ],
});
```

### `traceOpts`

传递给 [nf3](https://github.com/unjs/nf3) 的依赖追踪高级选项。

```ts
export default defineConfig({
  traceOpts: {
    // 传递给 @vercel/nft 的文件追踪选项
    nft: { /* ... */ },
    // 追踪时的模块路径别名
    traceAlias: { "old-pkg": "new-pkg" },
    // 复制时保留或设置文件权限（true 或类似 0o755 的八进制值）
    chmod: true,
    // 复制前转换已追踪文件
    transform: [
      { filter: (id) => id.endsWith(".js"), handler: (code) => code },
    ],
    // 接入追踪生命周期
    hooks: {
      tracedPackages(pkgs) {
        console.log("已追踪的包：", Object.keys(pkgs));
      },
    },
  },
});
```

### `oxc`

rolldown 构建的 OXC 选项。包含 `minify` 和 `transform` 子选项。

```ts
export default defineConfig({
  oxc: {
    minify: { compress: true, mangle: true },
  },
});
```

## 高级配置

底层选项。大多数项目无需更改这些选项。

### `dev`

- 开发环境中的默认值：`true`{lang=ts}；生产环境中的默认值：`false`{lang=ts}

::warning
这是高级配置。如果配置错误，可能会出现问题。
::

```ts
export default defineConfig({
  dev: true, // 强制使用开发模式行为
});
```

### `typescript`

- 默认值：`{}`{lang=ts}

TypeScript 选项。`tsConfig` 是打包工具用于 JSX 选项和路径别名的配置，默认为项目的 `tsconfig.json`。

```ts
export default defineConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        jsx: "react-jsx",
      },
    },
  },
});
```

### `hooks`

::warning
这是高级配置。如果配置错误，可能会出现问题。
::

Nitro 钩子。更多信息请参见 [hookable](https://github.com/unjs/hookable)。

```ts
export default defineConfig({
  hooks: {
    compiled(nitro) {
      console.log("构建编译成功！"); // 构建编译成功！
    },
  },
});
```

:read-more{to="/docs/lifecycle"}

### `commands`

::warning
这是高级配置。如果配置错误，可能会出现问题。
::

预览和部署命令提示通常由部署预设填充。

`deploy` 可以是 shell 命令（`./` 路径会相对于输出目录解析），也可以是接收 Nitro 实例的函数，供以编程方式部署的预设使用。两者都可以通过 [`nitro deploy`](/docs/cli#nitro-deploy) 和 [`deploy`](/docs/utils#nitrobuilder) builder API 运行。

```ts
export default defineConfig({
  commands: {
    preview: "node ./server/index.mjs",
    deploy: "npx wrangler deploy ./server/index.mjs",
  },
});
```

### `devErrorHandler`

::warning
这是高级配置。如果配置错误，可能会出现问题。
::

用于处理开发错误的自定义错误处理函数。

```ts
export default defineConfig({
  devErrorHandler: (error, event) => {
    return new Response(`开发错误：${error.message}`, { status: 500 });
  },
});
```

### `tracingChannel`

**🧪 实验性功能！**

- 类型：`boolean`{lang=ts} | `{ srvx?: boolean, h3?: boolean, unstorage?: boolean }`{lang=ts}
- 默认值：`false`{lang=ts}

`tracingChannel` 选项为请求处理启用 [`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel) 插桩。它已针对 Node.js 配置，也适用于 Bun、Deno 和开发预设，以及任何公开 `node:diagnostics_channel` 的运行时。已发布的 `srvx.request` 和 `h3.request` 通道在这些运行时中仍然可用，可供 APM 工具和自定义订阅程序使用。

传入 `true` 可同时启用两个通道；也可以传入对象分别控制每个通道是否启用。

```ts
export default defineConfig({
  tracingChannel: true,
});
```

### `framework`

- 默认值：`{ name: "nitro", version: "<current>" }`{lang=ts}

框架信息。由预设和构建信息使用。通常由更高级的框架设置（例如 Nuxt）。

```ts
export default defineConfig({
  framework: { name: "my-framework", version: "2.0.0" },
});
```

### `manifest`

构建清单选项。使用 `deploymentId` 可在构建清单中包含自定义部署标识符（某些预设会自动从平台环境变量中填充此项）。

```ts
export default defineConfig({
  manifest: { deploymentId: process.env.DEPLOY_ID },
});
```

## 预设选项

使用匹配的[部署预设](/deploy)时应用的提供商专属选项。

### `awsAmplify`

AWS Amplify 预设的选项。主要字段包括 `catchAllStaticFallback`、`imageOptimization`（`path`、`cacheControl`）、`imageSettings` 和 `runtime`（`nodejs20.x` | `nodejs22.x` | `nodejs24.x`）。参见[预设文档](/deploy/providers/aws-amplify)。

```ts
export default defineConfig({
  awsAmplify: {
    runtime: "nodejs22.x",
    imageOptimization: { path: "/_image", cacheControl: "public, max-age=3600" },
  },
});
```

### `awsLambda`

AWS Lambda 预设的选项。将 `streaming` 设置为 `true` 可启用响应流式传输。参见[预设文档](/deploy/providers/aws)。

```ts
export default defineConfig({
  awsLambda: {
    streaming: true,
  },
});
```

### `azure`

Azure Static Web Apps 预设的选项。使用 `config` 自定义生成的 `staticwebapp.config.json`（例如 `platform.apiRuntime`、`navigationFallback`）。参见[预设文档](/deploy/providers/azure)。

```ts
export default defineConfig({
  azure: {
    config: { platform: { apiRuntime: "node:20" } },
  },
});
```

### `firebase`

Firebase Functions 预设的选项。参见[预设文档](/deploy/providers/firebase#options)。

```ts
export default defineConfig({
  firebase: {
    gen: 2, // 使用 Cloud Functions 第二代
    region: "us-central1",
  },
});
```

### `iis`

IIS 预设的选项。使用 `mergeConfig` 将生成的 `web.config` 与现有配置合并，或使用 `overrideConfig` 完全替换该配置。参见[预设文档](/deploy/providers/iis)。

```ts
export default defineConfig({
  iis: {
    mergeConfig: true,
  },
});
```

### `netlify`

Netlify 预设的选项。使用 `config` 提供 Netlify [部署配置](https://docs.netlify.com/build/frameworks/frameworks-api/)（`headers`、`redirects`、`functions`、`edge_functions`、`images`，……）。参见[预设文档](/deploy/providers/netlify)。

```ts
export default defineConfig({
  netlify: {
    config: {
      redirects: [{ from: "/old", to: "/new", status: 301 }],
    },
  },
});
```

### `vercel`

Vercel 预设的选项。参见[预设文档](/deploy/providers/vercel)。

```ts
export default defineConfig({
  vercel: {
    config: { runtime: "nodejs20.x" },
  },
});
```

### `cloudflare`

Cloudflare 预设的选项。参见[预设文档](/deploy/providers/cloudflare)。

```ts
export default defineConfig({
  cloudflare: {
    wrangler: { compatibility_date: "2025-01-01" },
  },
});
```

### `zephyr`

Zephyr 预设的选项。参见[预设文档](/deploy/providers/zephyr#options)。