配置 - Nitro 中文文档

一般设置

`preset`

使用 preset 选项 NITRO_PRESET 环境变量来设置自定义的生产预设。

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

当未设置 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`

默认: {}

存储配置，详细信息请参见存储层部分。

`renderer`

主要渲染路径（文件应作为默认导出事件处理程序）。

`serveStatic`

类型: boolean | 'node' | 'deno'
默认: 取决于使用的部署预设。

在生产中提供 public/ 资产。

注意: 强烈建议您的边缘 CDN（Nginx、Apache、Cloud）提供 .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 将为公共资产和大于 1024 字节的预渲染路由生成预压缩（gzip 和/或 brotli）版本。使用最佳压缩级别。使用此选项，您可以支持零开销资产压缩而无需使用 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 包装。

有关所有可用缓存选项，请参见缓存 API。

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

示例：

routeRules: {
  '/blog/**': { swr: true },
  '/blog/**': { swr: 600 },
  '/blog/**': { static: true },
  '/blog/**': { cache: { /* 缓存选项*/ } },
  '/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 时 hitting 一些速率限制。

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

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

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

预渲染器将尝试渲染页面 3 次，间隔 500 毫秒。使用 retry 和 retryDelay 来更改此行为。