Nitro Server Entry

server entry 是 Nitro 中的一个特殊处理器，它作为全局中间件，在路由匹配之前为每个传入请求运行（参见请求生命周期）。它通常用于横切关注点，如身份验证、日志记录、请求预处理或创建自定义路由逻辑。

自动检测的 server.ts

默认情况下，Nitro 会自动在项目根目录或扫描目录中查找 server.ts（或 .js、.mjs、.tsx 等）文件。

如果找到，Nitro 将使用它作为 server entry 并为所有传入请求运行它。

export default {
  async fetch(req: Request) {
    const url = new URL(req.url);

    // 处理特定路由
    if (url.pathname === "/health") {
      return new Response("OK", {
        status: 200,
        headers: { "content-type": "text/plain" }
      });
    }

    // 为所有请求添加自定义头
    // 不返回任何内容以继续到下一个处理器
  }
}

import { defineHandler } from "nitro/h3";

export default defineHandler((event) => {
  return { hello: "API" };
});

使用此设置：

• /health → 由 server entry 处理
• /api/hello → 首先运行 server entry，然后运行 API route
• /about 等 → 首先运行 server entry，然后继续到 routes 或 renderer

框架兼容性

server entry 是与其他框架（如 Elysia、Hono 或 H3）集成的绝佳方式。

import { H3 } from "h3";

const app = new H3()

app.get("/", () => "⚡️ Hello from H3!");

export default app;

import { Hono } from "hono";

const app = new Hono();

app.get("/", (c) => c.text("🔥 Hello from Hono!"));

export default app;

import { Elysia } from "elysia";

const app = new Elysia();

app.get("/", (c) => "🦊 Hello from Elysia!");

export default app;

自定义 server entry 文件

你可以使用 Nitro 配置中的 serverEntry 选项指定自定义 server entry 文件。

import { defineNitroConfig } from 'nitro/config'

export default defineNitroConfig({
  serverEntry: './nitro.server.ts'
})

使用事件处理器

你也可以使用 defineHandler 导出事件处理器，以获得更好的类型推断和对 h3 事件对象的访问：

import { defineHandler } from "nitro/h3";

export default defineHandler((event) => {
  // 添加自定义上下文
  event.context.requestId = crypto.randomUUID();
  event.context.timestamp = Date.now();

  // 记录请求
  console.log(`[${event.context.requestId}] ${event.method} ${event.path}`);

  // 继续到下一个处理器（不返回任何内容）
});

请求生命周期

server entry 作为全局中间件堆栈的一部分被调用，在路由规则之后但在路由处理器之前：

1. Server hook: `request`
2. 路由规则（头、重定向等）
3. 全局中间件（middleware/）
4. Server entry ← 你在这里
5. 路由（routes/）
6. Renderer（renderer.ts 或 index.html）

将 server entry 视为在路由匹配之前运行的最后一个全局中间件。

最佳实践

• 使用 server entry 处理影响所有路由的横切关注点
• 返回 undefined 以继续处理，返回响应以终止
• 保持 server entry 逻辑轻量以获得更好的性能
• 使用全局中间件处理模块化关注点，而不是一个大的 server entry
• 考虑使用 Nitro plugins 进行初始化逻辑
• 避免在 server entry 中进行繁重计算（它为每个请求运行）
• 不要将 server entry 用于路由特定逻辑（使用路由处理器代替，因为它们性能更好）