深入理解unjs/nitro中的自定义预设(Custom Presets)-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00197/article/details/148464497

深入理解unjs/nitro中的自定义预设(Custom Presets)

nitro Create, build and deploy universal web servers. The open engine powering Nuxt and open to everyone. 项目地址: https://gitcode.com/gh_mirrors/ni/nitro

什么是Nitro预设？

在unjs/nitro框架中，预设(Preset)是一种预定义的配置模板，它包含了特定部署环境或平台所需的构建配置和运行时入口点。预设简化了将Nitro应用部署到不同环境的过程，开发者无需从头开始配置每个细节。

为什么需要自定义预设？

虽然Nitro提供了多种内置预设（如Node.js服务器、Vercel、边缘计算平台等），但在实际开发中可能会遇到以下情况：

需要部署到Nitro尚未支持的平台或服务
现有预设不能满足特定业务需求
需要对现有预设进行深度定制

这时，创建自定义预设就是最佳解决方案。

创建自定义预设的步骤

1. 创建预设目录结构

首先在项目中创建预设目录，通常命名为preset，包含两个核心文件：

/preset
  ├── nitro.config.ts  # 预设配置文件
  └── entry.ts        # 运行时入口文件

2. 配置预设文件

nitro.config.ts是预设的核心配置文件，它定义了预设的基本行为和扩展关系：

import type { NitroPreset } from "nitro";
import { fileURLToPath } from "node:url"

export default <NitroPreset>{
  // 可以继承现有预设
  // extends: "node-server",
  
  // 指定运行时入口文件路径
  entry: fileURLToPath(new URL("./entry.ts", import.meta.url)),
  
  // 定义构建钩子
  hooks: {
    compiled() {
      // 构建完成后执行的逻辑
    },
  },
};

3. 编写运行时入口文件

运行时入口文件entry.ts负责启动服务器或处理请求，根据目标平台不同，实现方式也不同。

针对Serverless环境的示例：

import "#internal/nitro/virtual/polyfill";

const nitroApp = useNitroApp();

export default {
  fetch(request: Request) {
    const url = new URL(request.url);
    return nitroApp.localFetch(url.pathname + url.search, {
      context: {},
      host: url.hostname,
      protocol: url.protocol,
      method: request.method,
      headers: request.headers,
      body: undefined,
    });
  },
};

针对传统Node.js服务器的示例：

import "#internal/nitro/virtual/polyfill";
import { Server } from "node:http";
import { toNodeListener } from "h3";

const nitroApp = useNitroApp();
const server = new Server(toNodeListener(nitroApp.h3App));

server.listen(3000, (err) => {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`Listening on http://localhost:3000 (custom preset)`);
});

4. 应用自定义预设

在项目配置中引用自定义预设：

纯Nitro项目配置：

export default defineNitroConfig({
  preset: "./preset",
});

Nuxt项目配置：

export default defineNuxtConfig({
  nitro: {
    preset: "./preset",
  }
});

自定义预设的高级用法

继承现有预设

自定义预设可以继承现有预设，只需在配置中添加extends属性：

export default <NitroPreset>{
  extends: "node-server",
  // 其他自定义配置...
};

使用构建钩子

Nitro提供了多个构建钩子，可以在不同构建阶段执行自定义逻辑：

hooks: {
  compiled() {
    // 构建完成后执行的逻辑
  },
  beforeBuild() {
    // 构建前执行的逻辑
  },
  rollup: {
    // Rollup特定的钩子
  }
},

环境变量处理

可以在预设中定义环境变量的处理方式：

export default <NitroPreset>{
  // ...
  envVariables: {
    // 定义环境变量默认值
    MY_VAR: "default-value",
    // 标记为必需的环境变量
    REQUIRED_VAR: { required: true }
  }
};