配置

#配置文件

你可以使用配置文件自定义 Nitro。根据你的设置，在 nitro.config.ts 中定义选项，或者使用 Vite 插件时在 vite.config.ts 的 nitro 键下定义选项。

import { defineConfig } from "nitro";

export default defineConfig({
  // Nitro options
})

#支持的配置文件

Nitro 使用项目根目录中的 c12 加载配置（该目录由传递给 nitro CLI 的目录决定，默认为当前工作目录）。系统会按以下顺序检查位置，并使用第一个匹配的文件：

• nitro.config.{js,ts,mjs,cjs,mts,cts,json,jsonc,json5,yaml,yml,toml}
• .config/nitro.{js,ts,mjs,cjs,mts,cts,json,jsonc,json5,yaml,yml,toml}
• .config/nitro.config.{js,ts,mjs,cjs,mts,cts,json,jsonc,json5,yaml,yml,toml}

推荐使用 nitro.config.ts 这一约定。

同一目录下没有扩展名的 .nitrorc 文件也会被加载（使用 key=value 语法），并以低于主配置文件的优先级进行合并。

使用 Vite 插件时，也可以在 vite.config.ts 的 nitro 键中直接传入选项（如上所示）。

#环境特定配置

使用 c12 约定，你可以使用 $development 和 $production 键提供特定于环境的覆盖：

import { defineConfig } from "nitro";

export default defineConfig({
  logLevel: 3,
  $development: {
    // 仅在开发模式下应用的选项
    debug: true,
  },
  $production: {
    // 仅在生产构建中应用的选项
    minify: true,
  },
})

环境名称在 nitro dev 期间为 "development"，在 nitro build 期间为 "production"。

#扩展配置

你可以使用 extends 键从其他配置或预设进行扩展：

import { defineConfig } from "nitro";

export default defineConfig({
  extends: "./base.config",
})

#目录选项

Nitro 提供了多个选项来控制目录结构：

import { defineConfig } from "nitro";

export default defineConfig({
  serverDir: "server",
  buildDir: "node_modules/.nitro",
  output: {
    dir: ".output",
  },
})

#环境变量

某些 Nitro 行为可以使用环境变量进行配置。这些变量会在构建和启动时配置 Nitro 本身。若要向应用公开你自己的值，请改用运行时配置。

#运行时配置

运行时配置允许你向应用公开配置值，并使用环境变量在运行时覆盖这些值。这对于在不同环境（开发、预发布、生产）之间有所不同的值非常有用，例如 API 端点或功能标志。

首先，在配置文件中定义运行时配置。

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    apiToken: "dev_token", // `dev_token` 是默认值
  }
});

你现在可以使用 useRuntimeConfig() 访问运行时配置。

import { defineHandler } from "nitro";
import { useRuntimeConfig } from "nitro/runtime-config";

export default defineHandler((event) => {
  return useRuntimeConfig().apiToken; // 返回 `dev_token`
});

#嵌套对象

运行时配置支持嵌套对象。任何深度的键都使用 NITRO_ 前缀和 UPPER_SNAKE_CASE 转换映射到环境变量：

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    database: {
      host: "localhost",
      port: 5432,
    },
  },
});

#序列化

运行时配置值必须是可序列化的（字符串、数字、布尔值、普通对象和数组）。不可序列化的值（类实例、函数等）将在构建时触发警告。

配置中值为 undefined 或 null 的项将作为后备替换为空字符串（""）。

#本地开发

你可以使用环境变量更新运行时配置。在本地可以使用 .env 或 .env.local 文件，在生产环境中可以使用平台变量（见下文）。

在你的项目根目录创建一个 .env 文件：

NITRO_API_TOKEN="123"

重启开发服务器，访问 /api/example 端点，你应该会看到响应为 123，而不是 dev_token。

你仍然可以使用 import.meta.env 或 process.env 直接访问环境变量，但应避免在环境全局上下文中（模块顶层）读取它们，以防止出现意外行为。

#生产环境

你可以在生产环境中定义变量以更新运行时配置。

NITRO_API_TOKEN="123"

运行时配置中的键采用 camelCase，环境变量中采用 UPPER_SNAKE_CASE。

{
  helloWorld: "foo"
}

NITRO_HELLO_WORLD="foo"

#自定义环境前缀

你可以使用 nitro.envPrefix 运行时配置键配置次要的环境变量前缀。除了默认的 NITRO_ 前缀外，还会检查此前缀：

import { defineConfig } from "nitro";

export default defineConfig({
  runtimeConfig: {
    nitro: {
      envPrefix: "APP_",
    },
    apiToken: "",
  },
});

使用此配置，NITRO_API_TOKEN 和 APP_API_TOKEN 都将被检查作为覆盖值。

#环境变量展开

启用后，运行时配置字符串值中使用 {{VAR_NAME}} 语法的环境变量引用将在运行时展开：

import { defineConfig } from "nitro";

export default defineConfig({
  experimental: {
    envExpansion: true,
  },
  runtimeConfig: {
    url: "https://{{APP_DOMAIN}}/api",
  },
});

APP_DOMAIN="example.com"

在运行时，useRuntimeConfig().url 将解析为 "https://example.com/api"。