企业官网建设流程全解析

将 Nitro 应用部署到 Stormkit：零配置 preset 与自动化部署全流程指南

【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro

本篇指南以 Nitro 官方部署文档中的 Stormkit 章节为骨架，结合仓库内stormkitpreset 的源码实现，系统讲解如何在 Stormkit 平台上从创建应用、首次部署到日常自动部署的完整流程，并深入剖析 Nitro 为 Stormkit 生成的运行时入口如何处理请求与响应。读完本文，你将掌握通过stormkitpreset 一键构建、零配置自动检测以及手动触发部署的完整实战方案。

Stormkit 集成概览：从零配置自动检测说起

Stormkit 是一个支持从 Git 仓库自动构建与发布的部署平台，Nitro 为其提供了内置部署 preset。在 Nitro 的部署体系中，Stormkit 属于零配置（Zero-Config）提供商——在 CI/CD 环境下执行生产构建时，Nitro 会尝试自动检测运行环境并选择合适的 preset，无需在配置中显式声明。

在 部署总览文档 的"Zero-Config Providers"一节中，Stormkit 与 AWS Amplify、Azure、Cloudflare、Firebase App Hosting、Netlify、Vercel、Zeabur 等平台并列，均可通过环境变量自动识别：

• 自动检测依赖 CI/CD 环境中的识别变量，构建时 Nitro 会自动选中stormkitpreset；
• 显式指定 preset 同样受支持，适用于无法自动检测的场景（详见下文"指定 stormkit preset 的三种方式"）。

需要提醒的是：对于使用 Turborepo 的用户，其 Strict Environment Mode 可能会干扰零配置检测。此时需要显式允许检测变量，或使用 Loose Environment Mode（即--env-mode=loose标志），否则检测可能失效。

部署前准备：在 Stormkit 上创建新应用

进入 Stormkit 控制台的 "New App" 创建流程后，需要完成两个关键步骤：选择代码库来源（支持 GitHub、Bitbucket、GitLab），并授权 Stormkit 访问你的仓库，以便后续拉取代码、执行构建并发布产物。

该界面位于创建应用流程的 Step 1 of 2，右侧的 "CI & CD" 说明框明确提示：授权 Git 提供商后，Stormkit 即可访问仓库并实现自动部署。这也正是"推送代码到主分支即可自动部署"这一行为的前提。

创建完成后，无需在 Stormkit 侧做任何 Nitro 相关的特殊配置——构建命令由平台默认执行，Nitro 会在构建阶段按stormkitpreset 产出平台所需的文件结构。

部署到 Stormkit：自动部署与手动触发

Nitro 官方文档明确了 Stormkit 的默认部署行为：

• 自动部署：当你向应用的主分支（main）推送变更时，Stormkit 会自动触发一次部署；
• 手动部署：对于首次部署等需要手动介入的场景，点击Deploy now按钮即可立即触发。

上图即手动部署的配置面板：可指定环境（production）、分支（main）、构建命令（Build Command）与构建文件夹（Build Folder），并可通过 "Publish deployment" 开关决定是否发布该次部署。底部醒目的红色Deploy now按钮用于立即执行部署。

手动触发适合以下场景：

• 应用创建完成后的首次部署（此时尚无任何推送记录触发构建）；
• 需要跳过 Git 推送、直接验证某个分支的构建结果；
• 平台自动检测/Webhook 异常时的兜底手段。

指定 stormkit preset 的三种方式

虽然 Stormkit 支持零配置自动检测，但掌握显式指定 preset 的方法依然是部署 CI/CD 的推荐实践。参考 部署总览 中"Changing the deployment preset"一节，有以下三种方式：

方式一：NITRO_PRESET环境变量（推荐用于 CI/CD）

NITRO_PRESET=stormkit nitro build

方式二：--preset命令行参数

nitro build --preset stormkit

方式三：在nitro.config.ts中配置

import { defineConfig } from "nitro"; export default defineConfig({ preset: "stormkit", });

三种方式等价，选择其一即可。在 CI/CD 流水线中，环境变量方式最为灵活，因为可以针对不同分支/环境切换 preset 而无需改动配置文件。

源码解析：stormkit preset 与运行时入口

preset 定义：构建产物的目录结构

仓库中 stormkit/preset.ts 定义了完整的 preset 配置：

import { defineNitroPreset } from "../_utils/preset.ts"; const stormkit = defineNitroPreset( { entry: "./stormkit/runtime/stormkit", output: { dir: "{{ rootDir }}/.stormkit", publicDir: "{{ rootDir }}/.stormkit/public/{{ baseURL }}", }, }, { name: "stormkit" as const, stdName: "stormkit", } ); export default [stormkit] as const;

关键信息如下：

其中{{ baseURL }}插值意味着：如果应用配置了baseURL（例如部署在子路径下），静态资源会自动输出到对应的子目录，无需手动迁移文件。

此外，presets/_all.gen.ts 将stormkitpreset 注册进全局 preset 列表，presets/_types.gen.ts 则将其纳入PresetName/PresetNameInput类型，保证preset: "stormkit"在 TypeScript 配置中拥有完整的类型提示。

运行时入口：事件到响应的完整转换

平台运行时入口 runtime/stormkit.ts 采用AWS Lambda Handler 风格（导入了aws-lambda的类型定义），Stormkit 会将部署事件以类似 Lambda 的格式传入。

入口定义了平台事件与响应结构：

type StormkitEvent = { url: string; // 例如 /my/path 或 /my/path?with=query path: string; method: string; body?: string; query?: Record<string, Array<string>>; headers?: Record<string, string>; rawHeaders?: Array<string>; }; type StormkitResponse = { headers?: Record<string, string>; body?: string; buffer?: string; // base64 编码的二进制响应体 statusCode: number; errorMessage?: string; errorStack?: string; };

核心处理逻辑分为四步：

1. 构造标准 Request：将 Stormkit 事件的url、method、headers、body组装为 Web 标准Request对象，随后交给 Nitro 应用处理：

const req = new Request(event.url, { method: event.method || "GET", headers: event.headers, body: event.body, }) as ServerRequest;

2. srvx 兼容：Nitro 内部基于 srvx 运行时抽象，入口通过req.runtime记录当前运行时名称与原始事件，便于插件、中间件按运行时分支处理：

req.runtime ??= { name: "stormkit" }; req.runtime.stormkit ??= { event, context } as any;

3. 调用 Nitro 应用：所有路由、中间件、Hooks 都在nitroApp.fetch(req)这一步统一执行，返回标准Response。

4. 响应编码：响应体需要按内容类型决定返回body（文本）还是buffer（base64 二进制）：

function isTextType(contentType = "") { return /^text\/|\/(javascript|json|xml)|utf-?8/i.test(contentType); }

• text/*、application/javascript、application/json、application/xml等文本类型直接以 UTF-8 字符串返回；
• 其余类型（如图片、字体、视频）转成 base64 放入buffer字段，并置isBase64Encoded标志，交由 Stormkit 平台还原为二进制内容。

响应头则会被拍平为Record<string, string>，重复值用逗号连接：

Object.fromEntries( Object.entries(headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(",") : String(v)]) );

从源码结构看，该入口通过"标准 Request 进、标准 Response 出"的设计，使 Stormkit 平台能够承载 Nitro 的全部能力——包括路由、服务端渲染、中间件、缓存与静态资源服务——而无需为平台特性编写额外代码。

构建产物一览：.stormkit目录

使用stormkitpreset 执行nitro build后，产物位于项目根目录的.stormkit文件夹：

.stormkit/ ├── public/ # 静态资源（对应 publicDir，支持 baseURL 子目录） └── ... # 服务端入口与其他构建产物

Stormkit 平台在构建完成后即从该目录读取并发布应用。对于public/下的静态资源（图片、CSS、JS 等），平台会直接托管；动态请求则交给运行时入口处理。

从零配置到手动部署：最佳实践小结

按照上述流程，你可以在数分钟内将 Nitro 应用接入 Stormkit 的自动化构建发布体系，并利用其 AWS Lambda 兼容的运行时入口获得与 Nitro 开发模式一致的完整服务端能力。

延伸阅读

• 部署总览与零配置提供商列表
• Node.js 运行时部署（默认生产 preset）
• 其他云平台 preset：Vercel、Cloudflare、Netlify
• Nitro 配置参考（preset 与 baseURL 等）

【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro