Nitro 中文文档

高级

底层选项。大多数项目都不需要修改这些选项。

Note

本页所有示例都假设已在 nitro.config.ts 中导入以下内容：

import { defineConfig } from "nitro";

#dev

  • 默认值：开发环境为 true，生产环境为 false

Warning

这是高级配置。配置错误可能导致问题。

export default defineConfig({
  dev: true, // force development mode behavior
});

#typescript

  • 默认值：{}

TypeScript 选项。tsConfig 是打包器用于 JSX 选项和路径别名的配置，默认为项目的 tsconfig.json。tsconfigPaths（默认值：true）会为服务器源文件解析其中的路径别名（compilerOptions.paths）。

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

#hooks

Warning

这是高级配置。配置错误可能导致问题。

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

export default defineConfig({
  hooks: {
    compiled(nitro) {
      console.log("Build compiled successfully!");
    },
  },
});

名称相同的钩子不会互相覆盖。部署预设定义的钩子会先运行，然后运行配置中的钩子。定义同名钩子不再会禁用预设中的钩子。

Read more in Docs > Lifecycle.

#commands

Warning

这是高级配置。配置错误可能导致问题。

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

deploy 可以是 Shell 命令（./ 路径相对于输出目录解析），也可以是接收 Nitro 实例的函数，供以编程方式部署的预设使用。两者都可通过 nitro deploy 和 deploy 构建器 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(`Dev error: ${error.message}`, { status: 500 });
  },
});

#tracingChannel

🧪 实验性功能

  • 类型：boolean | { srvx?: boolean, h3?: boolean, unstorage?: boolean, db0?: 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 },
});
Edit this page
Previous 构建 Next 预设选项