配置

常规

`preset`

使用 preset 选项 NITRO_PRESET 环境变量自定义生产 preset。

开发模式的 preset 始终是 nitro_dev，默认 node_server 用于构建独立的 Node.js 服务器。

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

`logLevel`

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

日志详细级别。更多信息请参阅 consola。

`runtimeConfig`

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

服务器 runtime 配置。

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

`compatibilityDate`

部署提供商引入了 Nitro preset 可以利用的新功能，但其中一些需要明确选择加入。

将其设置为最新测试日期（YY-MM-DD 格式）以利用最新的 preset 功能。

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

功能

`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 preset，使用内置的 SWR 功能（使用缓存层和存储），而不是回退到 ISR 行为。

`storage`

默认：{}

存储配置，在存储层部分阅读更多信息。

`renderer`

{ entry } 指向主渲染入口（文件应默认导出事件处理器）

`serveStatic`

类型：boolean | 'node' | 'deno'
默认：取决于使用的部署 preset。

在生产环境中提供 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`

自动导入选项。更多信息请参阅 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 { defineNitroConfig } from "nitro/config";
import { defineHandler } from "nitro/h3";

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

`devProxy`

开发服务器的代理配置。

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

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

有关所有可用的目标选项，请参阅 httpxy。

`errorHandler`

自定义 runtime 错误处理器的路径。替换 nitro 的内置错误页面。错误处理器被赋予一个 H3Error 和 H3Event。如果处理器返回一个 promise，它将被等待。处理器应该发送自己的响应。下面是一个使用 h3 函数返回纯文本响应的示例。

示例：

import { defineNitroConfig } from "nitro/config";

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

export default defineNitroErrorHandler((error, event) => {
  setResponseHeader(event, 'Content-Type', 'text/plain')
  return send(event, '[自定义错误处理器] ' + error.stack)
});

`routeRules`

🧪 实验性！

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

当设置 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，这对于避免达到某些速率限制很有用。

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

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

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

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

高级

`dev`

默认：开发时为 true，生产时为 false。

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

默认：false

压缩包。

`inlineDynamicImports`

避免创建 chunks。

`sourceMap`

启用源映射生成。参见选项

默认：true

Deploy Nitro apps to Zerops.

Nitro 中文文档术语表