配置

nitro.config.ts 中所有可用选项的参考文档。

#常规

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

#`preset`

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

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

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

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

#`defaultPreset`

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

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

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

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

#`debug`

默认值：false（当设置了 DEBUG 环境变量时为 true）

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

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

#`logLevel`

默认值：3（检测到测试环境时为 1）

日志详细程度级别。更多信息请参见 consola。

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

#`runtimeConfig`

默认值：{ app: {}, nitro: {} }

服务器运行时配置。Nitro 会将 app.baseURL（来自 baseURL 选项）注入 app 命名空间。

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

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

#`compatibilityDate`

未提供时的默认行为："latest"

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

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

#`static`

默认值：false

启用静态站点生成模式。

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

#功能特性

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

#`features`

默认值：{}

启用内置功能。

#`runtimeHooks`

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

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

#`websocket`

默认值：false

启用 WebSocket 支持。

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

#`experimental`

默认值：{}

启用实验性功能。

#`openAPI`

默认值：false

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

Note

建议优先使用顶级的 openAPI 选项进行配置。

#`typescriptBundlerResolution`

启用 TypeScript 打包器模块解析。参见 TypeScript#51669。

Note

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

#`asyncContext`

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

#`sourcemapMinify`

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

#`envExpansion`

允许在运行时配置中展开环境变量。参见配置指南和 #2043。

#`database`

启用实验性数据库支持。参见数据库。

#`tasks`

启用实验性任务支持。参见任务。

#`tracingLogger`

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

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

#`openAPI`

顶级 OpenAPI 配置。

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

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

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

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

要自定义 Scalar 集成，传入配置对象，例如：

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

要自定义 Swagger UI，请传入任意 Swagger UI 配置选项：

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

要自定义端点：

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

#`kv`

默认值：{}

KV 存储配置。

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

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

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

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

Note

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

#`cache`

默认值：{}

为缓存函数和处理器以及 cache 路由规则配置缓存存储和全局默认选项。

export default defineConfig({
  cache: {
    driver: "fs", // "memory" (default) | "fs" | "kv"
    fs: { dir: ".data/cache" },
    defaults: { maxAge: 60, swr: true },
  },
});

driver：memory（进程内 LRU）、fs（文件系统，仅兼容 Node.js 的运行时）或 kv（kv 存储层）。配置了 cache KV 挂载点时默认为 kv，否则默认为 memory。
memory：memory 驱动的 maxSize 和 maxBytes 限制。
fs：fs 驱动的 dir（默认为 .data/cache）。
defaults：所有缓存的全局默认选项（maxAge、swr、staleMaxAge、maxResolveTime、base，以及仅适用于处理器的 varies、allowQuery、allowCookies、allowAuthorization、sendCacheControl、cacheStatusHeader 和 maxBodySize）。

#`database`

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

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

#`devDatabase`

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

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

#`renderer`

类型：false | { handler?: string, static?: boolean, template?: string }

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

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

#`ssrRoutes`

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

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

#`serveStatic`

类型：boolean | 'node' | 'inline'
默认值：取决于所用的部署预设。

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

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

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

#`noPublicDir`

默认值：false

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

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

#`publicAssets`

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

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

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

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 选项是它们在提供服务/打包时可访问的文件夹路径。

#`compressPublicAssets`

类型：boolean | { gzip?: boolean, brotli?: boolean, zstd?: boolean }
默认值：false

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

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

#`serverAssets`

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

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

#`modules`

默认值：[]

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

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

#`plugins`

默认值：[]

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

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

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

#`tasks`

默认值：{}

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

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

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: "为数据库填充数据",
    },
  },
});

#`scheduledTasks`

默认值：{}

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

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

#`virtual`

默认值：{}

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

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

#`ignore`

默认值：[]

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

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

测试文件（*.test.ts、*.spec.ts）和类型声明文件（*.d.ts）始终会被忽略。

#`scanSuffixes`

默认值：[]

要保留在扫描文件名中的额外点分后缀。Nitro 将扫描文件名末尾的小写后缀（例如 .get 或 .dev）保留给自身约定使用。已知文件扩展名（例如 .json、.md、.xml）始终会保留。参阅保留后缀。

export default defineConfig({
  scanSuffixes: ["prompt"], // routes/system.prompt.ts -> /system.prompt
});

#`wasm`

类型：false | UnwasmPluginOptions
默认值：{}

WASM 支持配置。有关选项请参见 unwasm。

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

#开发

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

#`devServer`

默认值：{ watch: [] }

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

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

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

默认情况下，开发服务器会提供 /.well-known/appspecific/com.chrome.devtools.json，以便 Chrome DevTools 将项目文件夹作为自动工作区连接，并将编辑保存回源文件。工作区 UUID 会持久化在 buildDir 中。设置 devServer.devtoolsJson: false 可禁用此功能。

#`watchOptions`

开发模式的监听选项。更多信息请查看 chokidar。

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

#`devProxy`

开发服务器的代理配置。

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

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

路由匹配方式与其他 Nitro 路由相同：/proxy/test 只匹配该确切路径，使用 /proxy/test/** 也可代理子路径。设置 ws: true 还可代理 WebSocket 升级请求。

查看 httpxy 了解所有可用的目标选项。

Note

Bun 或 Deno 运行开发服务器时（例如 bun --bun nitro dev），会使用该运行时的原生服务器监听。HTTP 请求随后由 httpxy 的 proxyFetch 代理，支持 target、headers、auth、xfwd、changeOrigin、secure、ssl、agent、prependPath、ignorePath、proxyTimeout 和 followRedirects。WebSocket 请求由 crossws 代理，支持 target、headers、auth、xfwd、prependPath 和 ignorePath（上游 Host 标头始终与目标匹配）。只有在 Node.js 上才能将 WebSocket 升级请求代理到 miniflare 运行器（Cloudflare 预设）的开发 Worker。

#日志

#`logging`

默认值：{ compressedSizes: true, buildSuccess: true }

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

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

#路由

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

#`baseURL`

默认值："/"（如果提供，则使用 NITRO_APP_BASE_URL 环境变量）

服务器的主基础 URL。

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

#`apiBaseURL`

默认值："/api"

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

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

#`serverEntry`

类型：false | string | { handler: string, format?: EventHandlerFormat }

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

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

#`handlers`

服务器处理程序和路由。

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

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

#`devHandlers`

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

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

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

#`routes`

默认值：{}

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

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

#`errorHandler`

类型：string | string[]

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

import { defineConfig } from "nitro";

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

#`routeRules`

🧪 实验性功能！

路由选项。它是从路由模式（遵循 rou3）到路由选项的映射。

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

查看缓存 API了解所有可用的缓存选项。

Note

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

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/**' },
}

#`prerender`

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

默认值：

{
  autoSubfolderIndex: true,
  concurrency: 1,
  interval: 0,
  failOnError: false,
  crawlLinks: false,
  ignore: [],
  routes: []
}

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

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

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

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

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

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

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

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

#目录

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

#`workspaceDir`

项目工作空间根目录。

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

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

#`rootDir`

项目主目录。

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

#`serverDir`

类型：boolean | "./" | "./server" | string
默认值：false

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

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

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

#`scanDirs`

默认值：[]（为空时会扫描服务器源目录）

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

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

#`apiDir`

默认值："api"

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

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

#`routesDir`

默认值："routes"

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

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

#`buildDir`

默认值："node_modules/.nitro"

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

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

#`output`

默认值：{ dir: '.output', serverDir: '.output/server', publicDir: '.output/public' }

生产包的输出目录。

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

#构建

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

#`builder`

类型："rollup" | "rolldown" | "vite" | false
默认值：undefined（自动检测）

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

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

未设置时，如果你的 vite.config 使用了 nitro() 插件，Nitro 会使用 vite；否则使用 rolldown。构建器软件包会从你的项目中解析（rolldown 也可以通过你的 vite 解析），并在构建时按需安装。在开发环境中，如果没有安装 rolldown，且未设置 rollupConfig 或 rolldownConfig，nitro dev 会在没有构建器的情况下运行（builder: false），而 nitro build 会提示安装构建器。

设置 builder: false（实验性）可在不打包的情况下运行服务器源代码。此时，nitro dev 会直接在 env-runner worker 中运行你的文件，Nitro 虚拟模块由内存提供，并会在每次变更时启动新的 worker。nitro preview 也会以相同方式在生产模式下运行源代码，无需构建步骤（在使用 standard 预设的 Node.js worker 中运行，并忽略任何先前的构建输出）。预渲染也会以相同方式运行源代码；当未安装 rolldown 时，vite 构建器也会使用此方式。目前尚不支持 nitro build。

模块会像打包构建一样按需转换：TypeScript 和 JSX、import.meta.* 和 replace 值、alias、省略扩展名的导入、raw:/text/bytes 导入以及 WebAssembly。

Note

在 Bun 上，尚无法解析没有文件扩展名的别名（例如 ~/utils）和 WebAssembly 导入。
项目、项目扫描目录和 Nitro 之外的文件（例如链接的 workspace 软件包）会原样加载，不进行这些转换。
打包器选项（rollupConfig、rolldownConfig）以及模块通过 build:config 钩子添加的插件不会生效。请使用 buildPlugins 添加插件。

#`buildPlugins`

类型：NitroBuildPluginOption[]
默认值：[]

适用于所有构建器（rollup、rolldown、vite 和 false）的构建插件。嵌套数组和 Promise 会被解析，假值条目会被跳过。

插件使用 Rollup 插件接口。优先使用带有 filter 的 resolveId、load 和 transform 钩子：所有构建器都支持这些钩子。

带有 enforce: "pre" 的插件会放在 Nitro 自身插件之前，其他插件放在之后（enforce: "post" 最后）。钩子自身的 order 优先级更高：Nitro 的一些钩子（例如虚拟模块解析）使用 order: "pre"，需要先于它们运行的钩子也应设置此值。

Note

不同构建器在插件前后的执行流程有所不同。使用 rolldown 时，transform 钩子收到的 TypeScript 和 JSX 尚未转换（插件运行后才会编译）；使用 rollup 时，enforce: "pre" 插件的钩子也会收到未转换的代码。使用 vite 时，Vite 自身的解析和转换会先运行。
使用 vite 时，插件只会作为打包器插件应用于 nitro 环境：不支持 Vite 专用选项和钩子（例如 apply 或 configureServer）。Vite 插件应添加到 Vite 的 plugins 中。
使用 builder: false 时，插件会在 env-runner 中运行，它只支持 resolveId、load 和 transform（插件上下文有限），并会对其他钩子发出警告。除非 filter 指定其他文件（通过 id 或 moduleType），钩子只会接收 JavaScript 和 TypeScript 模块；只有 filter 指定了 node_modules 时才会接收其中的文件。

export default defineConfig({
  buildPlugins: [
    {
      name: "my-virtual-module",
      resolveId: {
        filter: { id: /^virtual:my-module$/ },
        handler: (id) => `\0${id}`,
      },
      load: {
        filter: { id: /^\0virtual:my-module$/ },
        handler: () => `export default "Hello!"`,
      },
    },
  ],
});

Nitro 模块可以通过 nitro.options.buildPlugins.push(plugin) 添加插件。

#`rollupConfig`

额外的 rollup 配置。

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

#`rolldownConfig`

额外的 rolldown 配置。

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

#`vite`

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

path：要使用的 vite 包，可指定其目录或入口的路径或 file:// URL（与 deps.paths.vite 相同）。默认从项目根目录解析 vite。以编程方式运行 Vite 的框架应传入自身使用的 vite（例如 import.meta.resolve("vite")），以确保开发模块运行器与当前运行实例一致。
services：要注册为可通过 fetch 访问的其他 Vite 环境，格式为 { [name]: { entry } }。带有入口的服务器环境（例如 ssr）会自动注册。
assetsImport：启用 ?assets 导入，以收集入口点的 CSS 和 JS 资源（默认值：true）。
serverReload：仅服务器模块发生更改时，重新加载开发服务器（及浏览器）（默认值：true）。

export default defineConfig({
  vite: {
    path: import.meta.resolve("vite"),
    services: { api: { entry: "./src/api-entry.ts" } },
  },
});

#`deps`

Nitro 按需安装的可选依赖配置（例如 vite、rolldown、rollup、unstorage、db0、ocache 或 unenv）。

paths：按包名称显式指定要使用的包。每个值都是指向包目录或入口的路径或 file:// URL。相对路径以 rootDir 为基准解析。

默认情况下，Nitro 会从项目中解析这些包，并在缺失时按需安装。基于 Nitro 构建的框架也可以通过 deps.paths 传入自身的依赖副本，以确保运行的是框架所依赖的版本。对于 unstorage、db0、ocache 和 unenv，服务器构建产物也会使用这些包。显式指定的包不会被安装；如果其版本超出支持范围，Nitro 会发出警告。

export default defineConfig({
  deps: {
    paths: {
      unstorage: import.meta.resolve("unstorage"),
      ocache: import.meta.resolve("ocache"),
    },
  },
});

deps.paths.vite 是 vite.path 的别名。

#`entry`

打包工具的入口点。

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

#`alias`

模块解析的路径别名。

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

#`inject`

在打包内容中引用时，替换为导入的全局变量。值可以是模块 ID（默认导出），也可以是 [id, exportName] 元组。

将全局变量设为 false 可移除默认注入（例如为 node: false 构建添加的注入）。

export default defineConfig({
  inject: {
    Buffer: ["node:buffer", "Buffer"],
    performance: false,
  },
});

#`polyfills`

在服务器入口之前为执行副作用而导入的模块。条目前加上 ! 可移除默认 polyfill。

node: false 构建默认会添加 #nitro/runtime/polyfills/global、#nitro/runtime/polyfills/process、#nitro/runtime/polyfills/buffer 和 #nitro/runtime/polyfills/timers（例如 "!#nitro/runtime/polyfills/timers" 会移除 setImmediate polyfill）。

export default defineConfig({
  polyfills: ["./polyfills/intl.ts"],
});

#`builtinModules`

由目标运行时提供的模块，例如 cloudflare:workers 或 Deno 上的 node:fs。这些 ID 的导入会在输出中保持原样。

内置模块不会被打包、追踪或复制到输出中，因此这里只应列出运行时本身提供的模块。若要避免将 npm 软件包打入包中，请改用 traceDeps。当 node 为 true 时，Node.js 内置模块会自动处理。

条目前加上 ! 可移除默认项（例如预设添加的项）。

export default defineConfig({
  builtinModules: ["cloudflare:workers"],
});

Note

预设也会添加默认的 alias、inject、polyfills 和 builtinModules 条目（例如，Cloudflare 和 Deno 会映射它们原生支持的 Node.js 内置模块）。这些选项中自行设置的值始终优先。

unenv 选项已弃用。传给它的预设仍会生效，顺序是在预设默认值之后、你自己的选项之前。

#`minify`

默认值：false

压缩打包文件。

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

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

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

#`inlineDynamicImports`

默认值：false

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

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

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

#`sourcemap`

默认值：false

启用 source map 生成。查看选项。

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

#`node`

默认值：true

指定构建是否用于 Node.js。如果设置为 false，Nitro 会添加默认的 alias、inject 和 polyfills 条目，以填充 Node.js 全局变量和内置模块（使用 unenv），并调整其行为。

目标运行时未提供的 Node.js 内置模块（例如 Cloudflare 上的 node:inspector）会通过 unenv 填充。只有构建导入此类模块时，才会从你的项目中解析并按需安装 unenv。

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

#`replace`

构建时的字符串替换。

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

#`commonJS`

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

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

#`exportConditions`

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

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

#`noExternals`

默认值：false

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

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

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

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

#内联指定的包

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

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

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

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

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

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

Note

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

#`traceDeps`

默认值：[]

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

支持特殊前缀：

!pkg：从追踪中排除内置包。
pkg*：完整追踪，复制包的所有文件，而不仅是追踪到的文件。

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

#`traceOpts`

传递给 nf3 的依赖追踪高级选项。

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`

rollup 构建器的 OXC 选项。包含 minify 和 transform 子选项。

minify 使用 rolldown 的压缩器。如果未安装 rolldown，则会跳过压缩并显示警告。

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

#高级配置

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

#`dev`

开发环境中的默认值：true；生产环境中的默认值：false

Warning

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

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

#`typescript`

默认值：{}

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

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

#`hooks`

Warning

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

Nitro 钩子。更多信息请参见 hookable。

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

同名钩子不会互相覆盖。部署预设中定义的钩子会先运行，然后运行配置中的钩子。定义同名钩子不再会禁用预设中的钩子。

#`commands`

Warning

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

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

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

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

#`devErrorHandler`

Warning

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

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

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

#`tracingChannel`

🧪 实验性功能！

类型：boolean | { srvx?: boolean, h3?: boolean, unstorage?: boolean }
默认值：false

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

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

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

#`framework`

默认值：{ name: "nitro", version: "<current>" }

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

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

#`manifest`

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

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

#预设选项

使用匹配的部署预设时应用的提供商专属选项。

#`awsAmplify`

AWS Amplify 预设的选项。主要字段包括 catchAllStaticFallback、imageOptimization（path、cacheControl）、imageSettings 和 runtime（nodejs20.x | nodejs22.x | nodejs24.x，默认值为 nodejs22.x）。参阅预设文档。

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

#`awsLambda`

AWS Lambda 预设的选项。将 streaming 设置为 true 可启用响应流式传输。参见预设文档。

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

#`azure`

Azure Static Web Apps 预设的选项。使用 config 自定义生成的 staticwebapp.config.json（例如 platform.apiRuntime、navigationFallback）。参见预设文档。

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

#`firebase`

Firebase App Hosting 预设的选项。使用 appHosting 自定义生成的运行配置。参见预设文档。

export default defineConfig({
  firebase: {
    appHosting: {
      memoryMiB: 512,
      maxInstances: 10,
    },
  },
});

#`iis`

IIS 预设的选项。使用 mergeConfig 将生成的 web.config 与现有配置合并，或使用 overrideConfig 完全替换该配置。参见预设文档。

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

#`netlify`

Netlify 预设的选项。使用 config 提供 Netlify 部署配置（headers、redirects、functions、edge_functions、images，……）。参见预设文档。

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

#`vercel`

Vercel 预设的选项。参见预设文档。

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

#`cloudflare`

Cloudflare 预设的选项。参见预设文档。

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

#`zephyr`

Zephyr 预设的选项。参见预设文档。

Edit this page

Previous Zerops Next 示例

On this page

配置

#常规

#preset

#defaultPreset

#debug

#logLevel

#runtimeConfig

#compatibilityDate

#static

#功能特性

#features

#runtimeHooks

#websocket

#experimental

#openAPI

#typescriptBundlerResolution

#asyncContext

#sourcemapMinify

#envExpansion

#database

#tasks

#tracingLogger

#openAPI

#kv

#cache

#database

#devDatabase

#renderer

#ssrRoutes

#serveStatic

#noPublicDir

#publicAssets

#compressPublicAssets

#serverAssets

#modules

#plugins

#tasks

#scheduledTasks

#virtual

#ignore

#scanSuffixes

#wasm

#开发

#devServer

#watchOptions

#devProxy

#日志

#logging

#路由

#baseURL

#apiBaseURL

#serverEntry

#handlers

#devHandlers

#routes

#errorHandler

#routeRules

#prerender

#目录

#workspaceDir

#rootDir

#serverDir

#scanDirs

#apiDir

#routesDir

#buildDir

#output

#构建

#builder

#buildPlugins

#rollupConfig

#rolldownConfig

#vite

#deps

#entry

#alias

#inject

#polyfills

#builtinModules

#minify

#`preset`

#`defaultPreset`

#`debug`

#`logLevel`

#`runtimeConfig`

#`compatibilityDate`

#`static`

#`features`

#`runtimeHooks`

#`websocket`

#`experimental`

#`openAPI`

#`typescriptBundlerResolution`

#`asyncContext`

#`sourcemapMinify`

#`envExpansion`

#`database`

#`tasks`

#`tracingLogger`

#`openAPI`

#`kv`

#`cache`

#`database`

#`devDatabase`

#`renderer`

#`ssrRoutes`

#`serveStatic`

#`noPublicDir`

#`publicAssets`

#`compressPublicAssets`

#`serverAssets`

#`modules`

#`plugins`

#`tasks`

#`scheduledTasks`

#`virtual`

#`ignore`

#`scanSuffixes`

#`wasm`

#`devServer`

#`watchOptions`

#`devProxy`

#`logging`

#`baseURL`

#`apiBaseURL`

#`serverEntry`

#`handlers`

#`devHandlers`

#`routes`

#`errorHandler`

#`routeRules`

#`prerender`

#`workspaceDir`

#`rootDir`

#`serverDir`

#`scanDirs`

#`apiDir`

#`routesDir`

#`buildDir`

#`output`

#`builder`

#`buildPlugins`

#`rollupConfig`

#`rolldownConfig`

#`vite`

#`deps`

#`entry`

#`alias`

#`inject`

#`polyfills`

#`builtinModules`

#`minify`

#`inlineDynamicImports`

#`sourcemap`

#`node`

#`replace`

#`commonJS`

#`exportConditions`

#`noExternals`

#`traceDeps`