Nitro 中文文档

功能

启用并配置 Nitro 的内置能力，例如 OpenAPI、插件、模块和任务。

Note

本页所有示例都假设已在 nitro.config.ts 中导入以下内容：

import { defineConfig } from "nitro";

#features

  • 默认值：{}

启用内置功能。

#runtimeHooks

  • 默认值：自动检测（至少存在一个 Nitro 插件时启用）

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

#websocket

  • 默认值：false

启用 WebSocket 支持。

Read more in Docs > Websocket.

#fastResponse

  • 默认值：启用 node 时为 true，否则为 false

将全局 Response 替换为 srvx 的 FastResponse，使处理器中的 new Response() 在 Node.js 下跳过原生 Response 的开销。原生和快速响应都可以正常使用 instanceof Response 判断。

在没有 FastResponse 实现的运行时（Bun、Deno 和 Workers）中无效。

Note

FastResponse 会延迟读取响应体和响应头，并跳过部分构造函数校验。例如，在 Node.js 中 new Response("body", { status: 204 }) 不会抛出错误，而在其他运行时会。设置 fastResponse: false 可改用原生 Response。

export default defineConfig({
  features: {
    runtimeHooks: true,
    websocket: true, // enable WebSocket support
    fastResponse: false, // use the native global Response
  },
});

#experimental

  • 默认值：{}

启用实验性功能。

#openAPI

  • 默认值：false

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

Note

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

#typescriptBundlerResolution

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

Note

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

#asyncContext

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

#sourcemapMinify

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

#entriesAwareLibChunks

设为 false 可禁用按入口拆分的库分块（Rolldown 和 Vite 构建器）。

默认情况下，每个 node_modules 包的分块会按使用它的入口（主入口和延迟加载的路由处理器）拆分，因此启动时不会加载仅供延迟路由使用的代码。由许多小模块组成的包可能被拆分成许多小分块。禁用此选项会生成数量更少、体积更大的库分块。

#envExpansion

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

#database

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

#tasks

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

#tracingLogger

使用内置且无依赖的遥测接收器，将 Nitro 追踪通道的 span 输出到控制台；每个已完成的 span（h3、srvx、unstorage、db0 等）都会记录下来。需要启用 tracingChannel。

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

#openAPI

顶层 OpenAPI 配置。

可以传入对象来修改 OpenAPI 规范：

openAPI: {
  meta: {
    title: 'My Awesome Project',
    description: 'This might become the next big thing.',
    version: '1.0'
  }
}

这些路由在生产环境中默认禁用。若要启用，请使用 production 键。 "runtime" 支持使用中间件；"prerender" 效率最高，因为 JSON 响应是固定的。

openAPI: {
    // IMPORTANT: make sure to protect OpenAPI routes if necessary!
    production: "runtime", // or "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"
    }
  }
}
Read more in Docs > Openapi.

#renderer

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

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

export default defineConfig({
  renderer: {
    handler: "~/renderer", // path to the render handler
  },
});
Read more in Docs > Renderer.

#ssrRoutes

需要进行服务端渲染的路由。

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

#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",
  ],
});
Read more in Docs > Plugins.

#tasks

  • 默认值：{}

任务定义。每个键都是任务名称，并可选包含 handler 路径和 description。

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

import { fileURLToPath } from "node:url";

export default defineConfig({
  tasks: {
    "db:migrate": {
      description: "Run database migrations",
    },
    "db:seed": {
      handler: fileURLToPath(new URL("scripts/seed.ts", import.meta.url)),
      description: "Seed the database",
    },
  },
});
Read more in Docs > Tasks.

#scheduledTasks

  • 默认值：{}

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

export default defineConfig({
  scheduledTasks: {
    "0 * * * *": "cleanup:temp",
    "*/5 * * * *": ["health:check", "metrics:collect"],
  },
});
Read more in Docs > Tasks.

#scheduler

  • 默认值：{}

运行 scheduledTasks 的选项。

  • runner（默认值：true``）：使用内置 Cron 运行器在进程内运行 scheduledTasks。适用于 dev、node_*、bun和deno_server` 预设。

由其他机制（例如系统 Cron）触发定时任务时，请设置 runner: false。任务仍会保持注册，因此 runCronTasks() 和 /_nitro/tasks 开发路由仍可使用。平台定时任务（Cloudflare Cron Triggers、Vercel Cron Jobs）不受影响。

export default defineConfig({
  scheduler: { runner: false },
});

#virtual

  • 默认值：{}

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

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

#wasm

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

WASM 支持配置。可用选项参见 unwasm。

export default defineConfig({
  wasm: {}, // enable WASM import support
});
Edit this page
Previous 常规 Next 存储