配置 - Nitro 中文文档

一般设置

`preset`

使用 preset 选项环境变量 NITRO_PRESET 来定制生产预设。

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

当 preset 选项未设置并在已知环境中运行时，预设将自动被检测。

`logLevel`

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

日志的详细程度。有关更多信息，请参见 unjs/consola。

`runtimeConfig`

默认值: { nitro: { ... }, ...yourOptions }

服务器运行时配置。

注意: nitro 命名空间是保留的。

`compatibilityDate`

部署提供商引入了 Nitro 预设可以利用的新功能，但有些需要显式选择。

设置为 YY-MM-DD 格式的最新测试日期，以利用最新预设功能。

如果未提供此配置，Nitro 将继续使用当前（v2.9）行为，并显示警告。

功能

`experimental`

默认值: {}

启用实验性功能。

`openAPI`

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

默认值: false

要在您的路由上定义 OpenAPI 规范，请查看 defineRouteMeta

您可以传递一个对象于根级别来修改您的 OpenAPI 规范：

openAPI: {
  meta: {
    title: '我精彩的项目',
    description: '这可能成为下一个重大事物。',
    version: '1.0'
  }
}

这些端点在生产环境中默认禁用。要启用它们，请使用 production 键。 "runtime" 允许中间件使用，"prerender" 是最有效的，因为 JSON 响应是常量。

openAPI: {
    // 重要：确保保护 OpenAPI 端点（如果需要）！
    production: "runtime", // 或 "prerender"
}

如果您想定制 Scalar 集成，您可以像这样传递一个配置对象:

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

如果您想自定义端点：

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

`wasm`

启用对 WASM 的支持。

`legacyExternals`

启用后，将使用遗留（不稳定）实验性 rollup externals 算法。

`future`

默认值: {}

等待重大版本的新特性，以避免破坏性更改。

`nativeSWR`

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

`storage`

默认值: {}

存储配置，可以在 Storage Layer 部分中阅读更多信息。

`timing`

默认值: false

启用时间信息：

Nitro 启动时间日志
HTTP 响应中的 Server-Timing 头

`renderer`

主要渲染的路径（文件应默认导出一个事件处理器）

`serveStatic`

类型: boolean | 'node' | 'deno'
默认值: 根据使用的部署预设而定。

在生产中提供 public/ 资源。

注意: 强烈建议您的边缘 CDN（Nginx、Apache、Cloudflare）直接提供 .output/public/ 目录，而不是启用压缩和更高级别缓存。

`noPublicDir`

默认值: false

如果启用，禁用 .output/public 目录的创建。跳过复制 public/ 目录并且还禁用预渲染。

`publicAssets`

用于在开发中提供和在生产中打包的公共资产目录。

如果检测到 public/ 目录，则默认添加，但您也可以自行添加更多！

使用 maxAge 选项设置资产的 Cache-Control 头是可能的：

publicAssets: [
  {
    baseURL: "images",
    dir: "public/images",
    maxAge: 60 * 60 * 24 * 7, // 7 天
  },
],

上述配置将在 public/images/ 文件夹中的资产生成以下头：

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

dir 选项是文件在文件系统中的位置；baseURL 选项是在提供/打包时可以访问的文件夹。

`compressPublicAssets`

默认值: { gzip: false, brotli: false }

如果启用，Nitro 将为支持的公共资产类型和预渲染路由生成预压缩（gzip 和/或 brotli）版本，文件大小大于 1024 字节，放在公共目录中，使用最佳的压缩级别。使用此选项，您可以在不使用 CDN 的情况下支持零开销的资产压缩。

可压缩的 MIME 类型列表：

application/dash+xml
application/eot
application/font
application/font-sfnt
application/javascript
application/json
application/opentype
application/otf
application/pdf
application/pkcs7-mime
application/protobuf
application/rss+xml
application/truetype
application/ttf
application/vnd.apple.mpegurl
application/vnd.mapbox-vector-tile
application/vnd.ms-fontobject
application/wasm
application/xhtml+xml
application/xml
application/x-font-opentype
application/x-font-truetype
application/x-font-ttf
application/x-httpd-cgi
application/x-javascript
application/x-mpegurl
application/x-opentype
application/x-otf
application/x-perl
application/x-ttf
font/eot
font/opentype
font/otf
font/ttf
image/svg+xml
text/css
text/csv
text/html
text/javascript
text/js
text/plain
text/richtext
text/tab-separated-values
text/xml
text/x-component
text/x-java-source
text/x-script
vnd.apple.mpegurl

`serverAssets`

在服务器逻辑中可以访问的资产，并在生产中打包。阅读更多。

`devServer`

默认值: { watch: [] }

开发服务器选项。您可以使用 watch 在指定路径中的任何文件更改时使开发服务器重新加载。

`watchOptions`

开发模式的观察选项。有关更多信息，请参见 chokidar。

`imports`

自动导入选项。有关更多信息，请参见 unjs/unimport。

`plugins`

默认值: []

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

请注意 Nitro 在 plugins/ 目录中自动注册插件，了解更多。

`virtual`

默认值: {}

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

路由

`baseURL`

默认值: /（如果提供，则为 NITRO_APP_BASE_URL 环境变量）

服务器的主要基本 URL。

`apiBaseURL`

默认值 : /api

更改默认 api 基础 URL 前缀。

`handlers`

服务器处理程序和路由。

如果存在 server/routes/、server/api/ 或 server/middleware/ 目录，它们将自动添加到处理程序数组中。

`devHandlers`

常规处理程序是指要通过 rollup 导入和转换的处理程序的路径。

在某些情况下，我们希望直接提供程序化使用的处理程序实例。

我们可以使用 devHandlers，但是请注意它们 仅在开发模式下可用 且 无法在生产构建中使用。

例如：

import { defineEventHandler } from 'h3'

export default defineNitroConfig({
  devHandlers: [
    {
      route: '/',
      handler: defineEventHandler((event) => {
        console.log(event)
      })
    }
  ]
})

请注意 defineEventHandler 是来自 h3 库的助手函数。

`devProxy`

开发服务器的代理配置。

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

{
  devProxy: {
    '/proxy/test': 'http://localhost:3001',
    '/proxy/example': { target: 'https://example.com', changeOrigin: true }
  }
}

有关所有可用目标选项，请参见 unjs/httpxy。

`errorHandler`

自定义运行时错误处理程序的路径。替换 nitro 的内置错误页面。错误处理程序会收到一个 H3Error 和 H3Event。如果处理程序返回一个 Promise，它将被等待。预期的处理程序将发送自己的响应。以下是使用 h3 函数返回纯文本响应的示例。

示例：

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

`routeRules`

🧪 实验性！

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

当设置 cache 选项时，匹配模式的处理程序将自动包装在 defineCachedEventHandler 中。

请参见 Cache API 以获取所有可用缓存选项。

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

示例：

routeRules: {
  '/blog/**': { swr: true },
  '/blog/**': { swr: 600 },
  '/blog/**': { static: true },
  '/blog/**': { 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`

默认值:

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

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

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

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

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

interval 和 concurrency 选项让您控制预渲染的速度，这在调用外部 API 时可用于避免触及一些速率限制。

设置 autoSubfolderIndex 让您控制如何在 .output/public 目录中生成文件：

# autoSubfolderIndex: true (默认)
关于 -> .output/public/about/index.html
# autoSubfolderIndex: false
关于 -> .output/public/about.html

当您的主机提供商不提供有关尾随斜杠的选项时，此选项非常有用。

预渲染程序将尝试以 500 毫秒的延迟渲染页面 3 次。使用 retry 和 retryDelay 可以更改此行为。

高级

`dev`

默认值: true 适用于开发环境，false 适用于生产环境。

⚠️ 注意！这是高级配置。如果配置错误，可能会出现问题。

默认值: false

压缩打包。

`inlineDynamicImports`

避免创建块。

`sourceMap`

启用源映射生成。请参见 options

默认值: true

Zerops

将 Nitro 应用部署到 Zerops。