配置

#常规

预设、日志记录和运行时配置的核心选项。

#`preset`

用于生产环境构建的部署预设。也可以通过 NITRO_PRESET 环境变量设置。

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

如果未设置 preset 选项，且 Nitro 正在已知环境中运行，则会自动检测预设。

export default defineConfig({
  preset: "cloudflare_pages", // 部署到 Cloudflare Pages
});

#`defaultPreset`

自定义在未设置 preset 且未自动检测到任何已知托管提供商时使用的回退预设。

默认情况下，Nitro 会回退到基于运行时的预设（在这些运行时上运行时，使用 node，以及 deno 或 bun）。显式指定的 preset、NITRO_PRESET 环境变量，以及自动检测到的提供商（Vercel、Netlify、Cloudflare Pages 等）都优先于 defaultPreset。

它接受一个预设名称或内联预设定义。

export default defineConfig({
  defaultPreset: "node_cluster", // 默认使用 node_cluster 而不是 node_server
});

#`debug`

默认值：false（当设置了 DEBUG 环境变量时为 true）

启用调试模式以输出详细日志和额外的开发信息。

export default defineConfig({
  debug: true,
});

#`logLevel`

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

日志详细程度级别。更多信息请参见 consola。

export default defineConfig({
  logLevel: 4, // 详细日志
});

#`runtimeConfig`

默认值：{ app: {}, nitro: {} }

服务器运行时配置。Nitro 会将 app.baseURL（来自 baseURL 选项）注入 app 命名空间。

注意： app 和 nitro 命名空间保留供内部使用。

export default defineConfig({
  runtimeConfig: {
    apiSecret: "default-secret", // 使用 NITRO_API_SECRET 覆盖
  },
});

#`compatibilityDate`

未提供时的默认行为："latest"

部署提供商会引入 Nitro 预设可以利用的新功能，但其中一些功能需要显式启用。请将此项设置为你已测试过的最新日期，格式为 YYYY-MM-DD，以利用最新的预设功能。

export default defineConfig({
  compatibilityDate: "2025-01-01",
});

#`static`

默认值：false

启用静态站点生成模式。

export default defineConfig({
  static: true, // 预渲染所有路由
});

#功能特性

启用和配置 Nitro 的内置功能，例如存储、任务和资源。

#`features`

默认值：{}

启用内置功能。

#`runtimeHooks`

默认值：自动检测（如果至少有一个 nitro 插件则启用）

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

#`websocket`

默认值：false

启用 WebSocket 支持。

export default defineConfig({
  features: {
    runtimeHooks: true,
    websocket: true, // 启用 WebSocket 支持
  },
});

#`experimental`

默认值：{}

启用实验性功能。

#`openAPI`

默认值：false

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

Note

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

#`typescriptBundlerResolution`

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

Note

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

#`asyncContext`

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

#`sourcemapMinify`

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

#`envExpansion`

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

#`database`

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

#`tasks`

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

#`tracingLogger`

使用内置的无依赖遥测接收器，将 Nitro 跟踪通道的 span 记录到控制台；该接收器会记录每个已完成的 span（h3、srvx、unstorage，……）。需要启用 tracingChannel。

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

#`openAPI`

顶级 OpenAPI 配置。

你可以传递一个对象来修改你的 OpenAPI 规范：

openAPI: {
  meta: {
    title: '我的超棒项目',
    description: '这可能会成为下一个重大项目。',
    version: '1.0'
  }
}

默认情况下，这些路由在生产环境中是禁用的。要启用它们，请使用 production 键。 "runtime" 允许中间件使用，而 "prerender" 是最有效的，因为 JSON 响应是恒定的。

openAPI: {
    // 重要：如有必要，确保保护 OpenAPI 路由！
    production: "runtime", // 或 "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"
    }
  }
}

#`future`

默认值：{}

等待在主要版本中发布的新功能，以避免破坏性变更。

#`nativeSWR`

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

export default defineConfig({
  future: {
    nativeSWR: true,
  },
});

#`kv`

默认值：{}

KV 存储配置。

export default defineConfig({
  kv: {
    redis: {
      driver: "redis",
      url: "redis://localhost:6379",
    },
  },
});

使用 $development 键覆盖开发期间的挂载配置：

export default defineConfig({
  $development: {
    kv: {
      redis: {
        driver: "fs",
        base: "./data/redis", // 在开发环境中使用文件系统
      },
    },
  },
});

$development 仅适用于开发服务器。使用 $prerender 可在预渲染时覆盖挂载配置。具有不同 driver 的挂载会替换整个挂载；具有相同 driver 的挂载则会对其选项进行深度合并。

Note

以前名为 storage，现仍可作为已弃用的别名使用。已弃用的 devStorage 选项由 $development（以及 $prerender）中的 kv 替代。

#`database`

数据库连接配置。需要 experimental.database: true。

export default defineConfig({
  database: {
    default: {
      connector: "sqlite",
      options: { name: "db" },
    },
  },
});

#`devDatabase`

开发模式的数据库连接配置覆盖。

export default defineConfig({
  devDatabase: {
    default: {
      connector: "sqlite",
      options: { name: "db-dev" }, // 独立的开发数据库
    },
  },
});

#`renderer`

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

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

export default defineConfig({
  renderer: {
    handler: "~/renderer", // 渲染处理器的路径
  },
});

#`ssrRoutes`

应进行服务器端渲染的路由。

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

#`serveStatic`

类型：boolean | 'node' | 'inline'
默认值：取决于所用的部署预设。

在生产环境中提供 public/ 资源服务。

注意： 强烈建议让你的边缘 CDN（Nginx、Apache、Cloud）直接提供 .output/public/ 目录服务，以启用压缩和更高级别的缓存。

export default defineConfig({
  serveStatic: "node", // 使用 Node.js 提供静态资源服务
});

#`noPublicDir`

默认值：false

如果启用，将禁用 .output/public 目录的创建。跳过复制 public/ 目录，同时禁用预渲染。

export default defineConfig({
  noPublicDir: true, // 跳过 public 目录输出
});

#`publicAssets`

在开发中提供、在生产中打包的公共资源目录。

如果检测到 public/ 目录，它将被默认添加，但你也可以自己添加更多！

可以使用 maxAge 选项为资源设置 Cache-Control 标头：

export default defineConfig({
  publicAssets: [
    {
      baseURL: "images",
      dir: "public/images",
      maxAge: 60 * 60 * 24 * 7, // 7 天
    },
  ],
});

上述配置会在 public/images/ 文件夹下的资源中生成以下响应头：

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

dir 选项是你的文件在文件系统中的位置；baseURL 选项是它们在提供服务/打包时可访问的文件夹路径。

#`compressPublicAssets`

类型：boolean | { gzip?: boolean, brotli?: boolean, zstd?: boolean }
默认值：false

如果启用，Nitro 将为大于 1024 字节的公共资源和预渲染路由生成预压缩版本（gzip、brotli 和/或 zstd）到公共目录中。使用默认压缩级别。使用此选项，你可以在不使用 CDN 的情况下支持零开销资源压缩。

export default defineConfig({
  compressPublicAssets: {
    gzip: true,
    brotli: true, // 启用 gzip 和 brotli 预压缩
  },
});

#`serverAssets`

服务器逻辑中可访问并在生产中打包的资源。

export default defineConfig({
  serverAssets: [
    {
      baseName: "templates",
      dir: "./templates", // 将 templates/ 作为服务器资源打包
    },
  ],
});

#`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",
  ],
});

#`tasks`

默认值：{}

任务定义。每个键都是一个任务名称，可选配置 handler 路径和 description。

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

import { fileURLToPath } from "node:url";

export default defineConfig({
  tasks: {
    "db:migrate": {
      description: "运行数据库迁移",
    },
    "db:seed": {
      handler: fileURLToPath(new URL("scripts/seed.ts", import.meta.url)),
      description: "为数据库填充数据",
    },
  },
});

#`scheduledTasks`

默认值：{}

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

export default defineConfig({
  scheduledTasks: {
    "0 * * * *": "cleanup:temp",
    "*/5 * * * *": ["health:check", "metrics:collect"],
  },
});

#`virtual`

默认值：{}

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

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

#`ignore`

默认值：[]

扫描目录时要忽略的全局模式数组。

export default defineConfig({
  ignore: [
    "routes/_legacy/**", // 跳过旧版路由处理器
  ],
});

#`wasm`

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

WASM 支持配置。有关选项请参见 unwasm。

export default defineConfig({
  wasm: {}, // 启用 WASM 导入支持
});

#开发

仅影响开发服务器（nitro dev）的选项。

#`devServer`

默认值：{ watch: [] }

开发服务器选项。你可以使用 watch 来让开发服务器在指定路径中的任何文件发生变化时重新加载。

支持 port、hostname、watch 和 runner 选项。

export default defineConfig({
  devServer: {
    port: 3001,
    watch: ["./server/plugins"],
  },
});

#`watchOptions`

开发模式的监听选项。更多信息请查看 chokidar。

export default defineConfig({
  watchOptions: {
    ignored: ["**/node_modules/**", "**/dist/**"],
  },
});

#`devProxy`

开发服务器的代理配置。

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

export default defineConfig({
  devProxy: {
    "/proxy/test": "http://localhost:3001",
    "/proxy/example": { target: "https://example.com", changeOrigin: true },
  },
});

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

#日志

#`logging`

默认值：{ compressedSizes: true, buildSuccess: true }

控制构建日志行为。将 compressedSizes 设置为 false 可跳过报告压缩后的包大小。将 buildSuccess 设置为 false 可隐藏构建成功消息。

export default defineConfig({
  logging: {
    compressedSizes: false, // 跳过压缩大小报告
    buildSuccess: false,
  },
});

#路由

用于定义路由、处理程序和路由级行为的选项。

#`baseURL`

默认值："/"（如果提供，则使用 NITRO_APP_BASE_URL 环境变量）

服务器的主基础 URL。

export default defineConfig({
  baseURL: "/app/", // 在 /app/ 前缀下提供应用
});

#`apiBaseURL`

默认值："/api"

更改默认的 API 基础 URL 前缀。

export default defineConfig({
  apiBaseURL: "/server/api", // /server/api/ 下的 API 路由
});

#`serverEntry`

类型：false | string | { handler: string, format?: EventHandlerFormat }

自定义服务器入口点配置。设置为 false 可禁用默认服务器入口。

export default defineConfig({
  serverEntry: "./server.ts",
});

#`handlers`

服务器处理程序和路由。

如果服务器目录内存在 routes/、api/ 或 middleware/ 目录，它们将自动添加到 handlers 数组中。

export default defineConfig({
  handlers: [
    { route: "/health", handler: "./handlers/health.ts" },
    { route: "/admin/**", handler: "./handlers/admin.ts", method: "get" },
  ],
});

#`devHandlers`

以程序化实例而非文件路径形式提供的处理程序。与常规的 handlers 不同，后者由打包器导入和转换，而 devHandlers 接受直接传入的处理程序函数。

注意： 它们仅在开发模式下可用，不会包含在生产构建中。

export default defineConfig({
  devHandlers: [
    { route: "/__dev", handler: defineHandler(() => "仅开发环境路由") },
  ],
});

#`routes`

默认值：{}

内联路由定义。从路由模式到处理程序路径或处理程序选项的映射。

export default defineConfig({
  routes: {
    "/hello": "./routes/hello.ts",
    "/greet": { handler: "./routes/greet.ts", method: "post" },
  },
});

#`errorHandler`

类型：string | string[]

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

import { defineConfig } from "nitro";

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

#`routeRules`

🧪 实验性功能！

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

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

查看缓存 API了解所有可用的缓存选项。

Note

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

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

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

默认值：

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

以 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 来更改此行为。

将 ignoreUnprefixedPublicAssets 设置为 true，可跳过没有基础 URL 前缀的公共资源的预渲染。

#目录

自定义 Nitro 查找源文件和写入输出文件的位置。

#`workspaceDir`

项目工作空间根目录。

未设置 workspaceDir 选项时，会自动检测工作空间目录（例如 pnpm 工作空间）。

export default defineConfig({
  workspaceDir: "../", // monorepo 根目录
});

#`rootDir`

项目主目录。

export default defineConfig({
  rootDir: "./src/server",
});

#`serverDir`

类型：boolean | "./" | "./server" | string
默认值：false

用于扫描 api/、routes/、plugins/、utils/、middleware/、modules/ 和 tasks/ 文件夹的服务器目录。

设置为 false 时，禁用自动目录扫描。设置为 "./" 以使用根目录，或设置为 "./server" 以使用 server/ 子目录。

export default defineConfig({
  serverDir: "./server", // 扫描 `server/` 子目录
});

#`scanDirs`

默认值：[]（为空时会扫描服务器源目录）

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

export default defineConfig({
  scanDirs: ["./modules/auth/api", "./modules/billing/api"],
});

#`apiDir`

默认值："api"

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

export default defineConfig({
  apiDir: "endpoints", // 扫描 `endpoints/` 而不是 `api/`
});

#`routesDir`

默认值："routes"

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

export default defineConfig({
  routesDir: "pages", // 扫描 `pages/` 而不是 `routes/`
});

#`buildDir`

默认值："node_modules/.nitro"

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

export default defineConfig({
  buildDir: ".nitro", // 在项目根目录中使用 `.nitro/`
});

#`output`

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

生产包的输出目录。

export default defineConfig({
  output: {
    dir: "dist",
    serverDir: "dist/server",
    publicDir: "dist/public",
  },
});

#构建

打包工具选择和构建输出调整。

#`builder`

类型："rollup" | "rolldown" | "vite"
默认值：undefined（自动检测）

指定用于构建的打包工具。

export default defineConfig({
  builder: "vite",
});

#`rollupConfig`

额外的 rollup 配置。

export default defineConfig({
  rollupConfig: {
    output: { manualChunks: { vendor: ["lodash-es"] } },
  },
});

#`rolldownConfig`

额外的 rolldown 配置。

export default defineConfig({
  rolldownConfig: {
    output: { banner: "/* 使用 nitro 构建 */" },
  },
});

#`vite`

vite 打包工具和 nitro/vite 插件的选项。

path：要使用的 vite 包，可以是其目录或入口文件的路径或 file:// URL。默认情况下，会从项目根目录解析 vite。以编程方式运行 Vite 的框架应传入自己的 vite（例如 import.meta.resolve("vite")），以便开发模块运行器与正在运行的实例保持一致。

export default defineConfig({
  vite: {
    path: import.meta.resolve("vite"),
  },
});

#`entry`

打包工具的入口点。

export default defineConfig({
  entry: "./server/entry.ts", // 自定义入口文件
});

#`unenv`

用于环境兼容性的 unenv 预设。

export default defineConfig({
  unenv: {
    alias: { "my-module": "my-module/web" },
  },
});

#`alias`

模块解析的路径别名。

export default defineConfig({
  alias: {
    "~utils": "./src/utils",
    "#shared": "./shared",
  },
});

#`minify`

默认值：false

压缩打包文件。

某些预设（尤其是 worker 运行时）默认启用压缩。在调试生产环境、worker 或边缘构建时，将 minify: false 设置为 false，以便保持堆栈跟踪易于阅读。

export default defineConfig({
  minify: true, // 压缩生产包
});

export default defineConfig({
  minify: false, // 更方便地调试 worker／边缘程序包
});

#`inlineDynamicImports`

默认值：false

将所有代码打包到单个文件中，而不是为每个路由创建单独的块。

当为 false 时，每个路由处理程序都成为一个按需加载的独立块。当为 true 时，所有内容都打包在一起。某些预设默认启用此选项。

export default defineConfig({
  inlineDynamicImports: true, // 单个输出文件
});

#`sourcemap`

默认值：false

启用 source map 生成。查看选项。

export default defineConfig({
  sourcemap: true, // 生成 `.map` 文件
});

#`node`

默认值：true

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

export default defineConfig({
  node: false, // 面向非 Node.js 运行时
});

#`replace`

构建时的字符串替换。

export default defineConfig({
  replace: {
    "process.env.APP_VERSION": JSON.stringify("1.0.0"),
  },
});

#`commonJS`

指定 rollup CommonJS 插件的额外配置。

export default defineConfig({
  commonJS: {
    requireReturnsDefault: "auto",
  },
});

#`exportConditions`

模块解析的自定义导出条件。

export default defineConfig({
  exportConditions: ["worker", "production"],
});

#`noExternals`

默认值：false

禁止将包外部化。外部化的包会在运行时导入，而不是打包进去，因此它们无法使用你的 alias 配置。

在生产构建中，Nitro 已经会打包几乎所有内容：只有原生包或其他无法打包的包，以及 traceDeps 中列出的包会保留为外部依赖。在开发环境中，为了提高速度，node_modules 中的依赖会保留为外部依赖；此选项在这种情况下最为有用。

将其设为 true，可打包所有内容，包括通常保留为外部依赖的包：

export default defineConfig({
  noExternals: true, // 打包所有依赖项
});

#内联指定的包

传入数组，只内联部分模块。RegExp 条目按原样使用；字符串条目会经过转义，并按路径子字符串匹配。

每个模式都会与书写形式的导入说明符（例如 @scope/my-lib）以及解析后的绝对文件路径（例如 /…/node_modules/@scope/my-lib/dist/index.mjs）进行匹配。任一匹配成功都会使模块保持打包状态，因此通常只需提供包名称即可：

export default defineConfig({
  alias: {
    "@shared": "./shared",
  },
  noExternals: ["@scope/my-lib"],
});

如果需要更精确的匹配，例如在 monorepo 中内联一个包，同时避免匹配名称相似的其他包，请使用路径模式：

export default defineConfig({
  noExternals: [/packages[\\/]my-lib/],
});

在此类模式中使用 [\\/] 而不是 /，以便也能匹配 Windows 路径。

Note

在 Nitro 2 中，此选项名为 externals.inline。

#`traceDeps`

默认值：[]

要跟踪并包含在构建输出中的额外依赖项。

支持特殊前缀：

!pkg：从追踪中排除内置包。
pkg*：完整追踪，复制包的所有文件，而不仅是追踪到的文件。

export default defineConfig({
  traceDeps: [
    "sharp",
    "better-sqlite3",
    "my-pkg*", // 完整追踪（复制所有包文件）
    "!unwanted-pkg", // 从追踪中排除
  ],
});

#`traceOpts`

传递给 nf3 的依赖追踪高级选项。

export default defineConfig({
  traceOpts: {
    // 传递给 @vercel/nft 的文件追踪选项
    nft: { /* ... */ },
    // 追踪时的模块路径别名
    traceAlias: { "old-pkg": "new-pkg" },
    // 复制时保留或设置文件权限（true 或类似 0o755 的八进制值）
    chmod: true,
    // 复制前转换已追踪文件
    transform: [
      { filter: (id) => id.endsWith(".js"), handler: (code) => code },
    ],
    // 接入追踪生命周期
    hooks: {
      tracedPackages(pkgs) {
        console.log("已追踪的包：", Object.keys(pkgs));
      },
    },
  },
});

#`oxc`

rolldown 构建的 OXC 选项。包含 minify 和 transform 子选项。

export default defineConfig({
  oxc: {
    minify: { compress: true, mangle: true },
  },
});

#高级配置

底层选项。大多数项目无需更改这些选项。

#`dev`

开发环境中的默认值：true；生产环境中的默认值：false

Warning

这是高级配置。如果配置错误，可能会出现问题。

export default defineConfig({
  dev: true, // 强制使用开发模式行为
});

#`typescript`

默认值：{}

TypeScript 选项。tsConfig 是打包工具用于 JSX 选项和路径别名的配置，默认为项目的 tsconfig.json。

export default defineConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        jsx: "react-jsx",
      },
    },
  },
});

#`hooks`

Warning

这是高级配置。如果配置错误，可能会出现问题。

Nitro 钩子。更多信息请参见 hookable。

export default defineConfig({
  hooks: {
    compiled(nitro) {
      console.log("构建编译成功！"); // 构建编译成功！
    },
  },
});

#`commands`

Warning

这是高级配置。如果配置错误，可能会出现问题。

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

deploy 可以是 shell 命令（./ 路径会相对于输出目录解析），也可以是接收 Nitro 实例的函数，供以编程方式部署的预设使用。两者都可以通过 nitro deploy 和 deploy builder API 运行。

export default defineConfig({
  commands: {
    preview: "node ./server/index.mjs",
    deploy: "npx wrangler deploy ./server/index.mjs",
  },
});

#`devErrorHandler`

Warning

这是高级配置。如果配置错误，可能会出现问题。

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

export default defineConfig({
  devErrorHandler: (error, event) => {
    return new Response(`开发错误：${error.message}`, { status: 500 });
  },
});

#`tracingChannel`

🧪 实验性功能！

类型：boolean | { srvx?: boolean, h3?: boolean, unstorage?: boolean }
默认值：false

tracingChannel 选项为请求处理启用 TracingChannel 插桩。它已针对 Node.js 配置，也适用于 Bun、Deno 和开发预设，以及任何公开 node:diagnostics_channel 的运行时。已发布的 srvx.request 和 h3.request 通道在这些运行时中仍然可用，可供 APM 工具和自定义订阅程序使用。

传入 true 可同时启用两个通道；也可以传入对象分别控制每个通道是否启用。

export default defineConfig({
  tracingChannel: true,
});

#`framework`

默认值：{ name: "nitro", version: "<current>" }

框架信息。由预设和构建信息使用。通常由更高级的框架设置（例如 Nuxt）。

export default defineConfig({
  framework: { name: "my-framework", version: "2.0.0" },
});

#`manifest`

构建清单选项。使用 deploymentId 可在构建清单中包含自定义部署标识符（某些预设会自动从平台环境变量中填充此项）。

export default defineConfig({
  manifest: { deploymentId: process.env.DEPLOY_ID },
});

#预设选项

使用匹配的部署预设时应用的提供商专属选项。

#`awsAmplify`

AWS Amplify 预设的选项。主要字段包括 catchAllStaticFallback、imageOptimization（path、cacheControl）、imageSettings 和 runtime（nodejs20.x | nodejs22.x | nodejs24.x）。参见预设文档。

export default defineConfig({
  awsAmplify: {
    runtime: "nodejs22.x",
    imageOptimization: { path: "/_image", cacheControl: "public, max-age=3600" },
  },
});

#`awsLambda`

AWS Lambda 预设的选项。将 streaming 设置为 true 可启用响应流式传输。参见预设文档。

export default defineConfig({
  awsLambda: {
    streaming: true,
  },
});

#`azure`

Azure Static Web Apps 预设的选项。使用 config 自定义生成的 staticwebapp.config.json（例如 platform.apiRuntime、navigationFallback）。参见预设文档。

export default defineConfig({
  azure: {
    config: { platform: { apiRuntime: "node:20" } },
  },
});

#`firebase`

Firebase Functions 预设的选项。参见预设文档。

export default defineConfig({
  firebase: {
    gen: 2, // 使用 Cloud Functions 第二代
    region: "us-central1",
  },
});

#`iis`

IIS 预设的选项。使用 mergeConfig 将生成的 web.config 与现有配置合并，或使用 overrideConfig 完全替换该配置。参见预设文档。

export default defineConfig({
  iis: {
    mergeConfig: true,
  },
});

#`netlify`

Netlify 预设的选项。使用 config 提供 Netlify 部署配置（headers、redirects、functions、edge_functions、images，……）。参见预设文档。

export default defineConfig({
  netlify: {
    config: {
      redirects: [{ from: "/old", to: "/new", status: 301 }],
    },
  },
});

#`vercel`

Vercel 预设的选项。参见预设文档。

export default defineConfig({
  vercel: {
    config: { runtime: "nodejs20.x" },
  },
});

#`cloudflare`

Cloudflare 预设的选项。参见预设文档。

export default defineConfig({
  cloudflare: {
    wrangler: { compatibility_date: "2025-01-01" },
  },
});

#`zephyr`

Zephyr 预设的选项。参见预设文档。

Edit this page

Previous Zerops Next 示例

On this page

配置

#常规

#preset

#defaultPreset

#debug

#logLevel

#runtimeConfig

#compatibilityDate

#static

#功能特性

#features

#runtimeHooks

#websocket

#experimental

#openAPI

#typescriptBundlerResolution

#asyncContext

#sourcemapMinify

#envExpansion

#database

#tasks

#tracingLogger

#openAPI

#future

#nativeSWR

#kv

#database

#devDatabase

#renderer

#ssrRoutes

#serveStatic

#noPublicDir

#publicAssets

#compressPublicAssets

#serverAssets

#modules

#plugins

#tasks

#scheduledTasks

#virtual

#ignore

#wasm

#开发

#devServer

#watchOptions

#devProxy

#日志

#logging

#路由

#baseURL

#apiBaseURL

#serverEntry

#handlers

#devHandlers

#routes

#errorHandler

#routeRules

#prerender

#目录

#workspaceDir

#rootDir

#serverDir

#scanDirs

#apiDir

#routesDir

#buildDir

#output

#构建

#builder

#rollupConfig

#rolldownConfig

#vite

#entry

#unenv

#alias

#minify

#inlineDynamicImports

#sourcemap

#node

#replace

#`preset`

#`defaultPreset`

#`debug`

#`logLevel`

#`runtimeConfig`

#`compatibilityDate`

#`static`

#`features`

#`runtimeHooks`

#`websocket`

#`experimental`

#`openAPI`

#`typescriptBundlerResolution`

#`asyncContext`

#`sourcemapMinify`

#`envExpansion`

#`database`

#`tasks`

#`tracingLogger`

#`openAPI`

#`future`

#`nativeSWR`

#`kv`

#`database`

#`devDatabase`

#`renderer`

#`ssrRoutes`

#`serveStatic`

#`noPublicDir`

#`publicAssets`

#`compressPublicAssets`

#`serverAssets`

#`modules`

#`plugins`

#`tasks`

#`scheduledTasks`

#`virtual`

#`ignore`

#`wasm`

#`devServer`

#`watchOptions`

#`devProxy`

#`logging`

#`baseURL`

#`apiBaseURL`

#`serverEntry`

#`handlers`

#`devHandlers`

#`routes`

#`errorHandler`

#`routeRules`

#`prerender`

#`workspaceDir`

#`rootDir`

#`serverDir`

#`scanDirs`

#`apiDir`

#`routesDir`

#`buildDir`

#`output`

#`builder`

#`rollupConfig`

#`rolldownConfig`

#`vite`

#`entry`

#`unenv`

#`alias`

#`minify`

#`inlineDynamicImports`

#`sourcemap`

#`node`

#`replace`

#`commonJS`

#`exportConditions`

#`noExternals`

#`traceDeps`

#`traceOpts`

#`oxc`

#`dev`

#`typescript`