配置文件 Configuration

常规的 General

preset

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

开发模式的预设始终为 nitro-dev，生产模式的默认预设为 node-server，用于构建独立的 Node.js 服务器。

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

logLevel

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

日志详细程度。有关更多信息，请参阅 unjs/consola#level。

runtimeConfig

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

服务器运行时配置。

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

特性的 Features

experimental

• 默认值: {}

启用实验性功能。 目前，没有可用的！

openAPI

启用 /_nitro/scalar、/_nitro/swagger 和 /_nitro/openapi.json 端点。

• 默认值：false

!IMPORTANTScalar 支持目前在 nightly 频道 中提供。

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

{
  "openAPI": {
    "meta": {
      "title": "我的精彩项目",
      "description": "这可能会成为下一件大事。",
      "version": "1.0"
    }
  }
}

如果你喜欢自定义 Scalar 集成，你可以像这样传递配置对象：

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

wasm

启用 WASM 支持

legacyExternals

启用后，将使用旧的（不稳定的）实验性汇总外部算法。

future

• 默认值: {}

新功能需等待主要版本发布，以避免发生重大变化。

nativeSWR

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

storage

• 默认值: {}

存储配置，更多内容请阅读存储层章节。

timing

• 默认值: false

启用时间信息：

• Nitro 启动时间日志
• HTTP 响应上的Server-Timing标头

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 days
  },
]

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

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

dir 选项是您的文件在文件系统上的位置；baseURL 选项是它们在提供/捆绑时可从中访问的文件夹。

compressPublicAssets

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

如果启用，Nitro 将生成受支持类型的公共资产和预渲染路由的预压缩（gzip 和/或 brotli）版本，这些版本大于 1024 字节，并放入公共目录中。将使用最佳压缩级别。使用此选项，您可以支持零开销资产压缩，而无需使用 CDN。

serverAssets

资产可以在服务器逻辑中访问并在生产中捆绑。阅读更多。

devServer

• 默认值: { watch: [] }

开发服务器选项。如果指定路径中的任何文件发生变化，您可以使用“watch”来让开发服务器重新加载。

watchOptions

监视开发模式的选项。有关更多信息，请参阅 chokidar。

imports

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

plugins

• 默认值: []

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

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

virtual

• 默认值: {}

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

路由相关 Routing

baseURL

默认值: / 或 NITRO_APP_BASE_URL 环境变量 (如果提供)

服务器的主要基本 URL。

apiBaseURL

• 默认值 : /api

更改默认的 api 基本 URL 前缀。

handlers

服务器处理程序和路由。

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

devHandlers

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

在某些情况下，我们想直接提供一个具有编程用法的处理程序实例。

我们可以使用 devHandlers，但请注意，它们 仅在开发模式下可用，在生产版本中不可用。

例如:

import { defineEventHandler } from 'h3'

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

devProxy

开发服务器的代理配置。

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

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

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

errorHandler

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

错误处理程序被赋予 H3Error 和 H3Event。如果处理程序返回承诺，则等待它。

处理程序应发送自己的响应。下面是使用 h3 函数返回纯文本响应的示例。

示例：

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

export default defineNitroErrorHandler((error, event) => {
  setResponseHeader(event, 'Content-Type', 'text/plain')
  return send(event, `[custom error handler] ${error.stack}`)
})

routeRules

🧪 实验性！

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

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

请参阅 Cache API 了解所有可用的缓存选项。

例如:

{
  "routeRules": {
    "/blog/**": { "swr": true },
    "/blog1/**": { "swr": 600 },
    "/blog2/**": { "static": true },
    "/blog3/**": { "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" }, // uses status code 307 (Temporary Redirect)
    "/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": [],
  "retries": 3,
  "retryDelay": 500
}

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

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

如果 crawlLinks 选项设置为 true，则 nitro 默认以 / 开头（或 routes 数组中的所有路由），并且对于 HTML 页面，提取 <a> 标签并对其进行预渲染。

如果 Nitro 无法预渲染路由，您可以将 failOnError 选项设置为 true，以在发生错误时停止 CI。

interval 和 concurrency 选项可让您控制预渲染的速度，如果您调用外部 API，则可用于避免达到某些速率限制。

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

# autoSubfolderIndex: true (default)
/about -> .output/public/about/index.html
# autoSubfolderIndex: false
/about -> .output/public/about.html

当您的托管服务提供商未为您提供有关尾部斜杠的选项时，此选项非常有用。

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

目录的 Directories

rootDir

项目主目录

srcDir

项目源目录。除非指定，否则与rootDir相同。有助于将代码移动到src/。

scanDirs

• 默认值: （空数组时为源目录）

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

apiDir

• 默认值 : api

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

routesDir

• 默认值 : routes

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

buildDir

• 默认值: .nitro

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

output

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

生产包的输出目录。

进阶配置 Advanced

dev

• 默认值: true表示开发，false表示生产。

⚠️ 小心！这是一个高级配置。如果配置错误，可能会出错。

typescript

默认值: { generateTsConfig: true }

nodeModulesDirs

⚠️ 小心！这是一个高级配置。如果配置错误，可能会出错。

解析模块时要搜索的附加“node_modules”。默认情况下会添加用户目录。

hooks

⚠️ 小心！这是一个高级配置。如果配置错误，可能会出错。

nitro 钩子。有关更多信息，请参阅 unjs/hookable。

commands

⚠️ 小心！这是一个高级配置。如果配置错误，可能会出错。

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

devErrorHandler

⚠️ 小心！这是一个高级配置。如果配置错误，可能会出错。

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

Rollup

rollupConfig

附加汇总配置。

entry

汇总条目。

unenv

unjs/unenv 预设的选项。

alias

汇总别名选项。

minify

• 默认值: false

最小化包。

inlineDynamicImports

避免创建块。

sourceMap

启用源映射生成。请参阅 选项- 默认值：true

node

指定构建是否用于 Node.js。如果设置为 false，nitro 会尝试使用 unjs/unenv 模拟 Node.js 依赖项并调整其行为。

analyze

如果启用，将在构建后使用 rollup-plugin-visualizer 分析服务器包。您还可以传递自定义选项。

moduleSideEffects

默认值: ['unenv/runtime/polyfill/', 'node-fetch-native/polyfill']

Rollup 特定选项。指定具有副作用的模块导入

replace

Rollup 特定选项。

commonJS

Rollup 特定选项。指定 Rollup CommonJS 插件的附加配置。

预设选项

firebase

firebase 函数预设的选项。请参阅 预设文档

vercel

vercel 预设的选项。请参阅 预设文档

cloudflare

cloudflare 预设的选项。请参阅 预设文档