Orbit 中支持的框架和运行时

Orbit builds any project that installs with npm, yarn or pnpm and produces a folder of files or a Node.js server, and it detects the framework and package manager for you so most projects deploy…

Orbit 支持的框架和运行时

Orbit 可以构建任何使用 npm、yarn 或 pnpm 安装的项目，并生成文件夹或 Node.js 服务器，它会自动检测框架和包管理器，因此大多数项目无需任何构建配置即可部署。本指南涵盖自动检测的内容、每个常见框架所需的设置、何时必须启用服务器模式以及如何选择 Node.js 版本。

Orbit 自动检测的内容

构建运行时，Orbit 会记录它找到的内容并将其显示给你：

框架，在部署详情页面上和项目概览中部署卡上的徽章。
包管理器，从你的锁定文件中选择：package-lock.json 给出 npm，yarn.lock 给出 yarn，pnpm-lock.yaml 给出 pnpm。

设置中的构建设置都是可选的。留空字段，其占位符会告诉你将使用什么：安装命令显示 npm ci (auto-detected)，构建命令显示 npm run build (auto-detected)，输出目录显示 dist (auto-detected)。

Orbit 项目设置中的构建设置

仅提交一个锁定文件。如果 package-lock.json 和 yarn.lock 都在存储库中，Orbit 选择的包管理器可能不是你在本地使用的，你会得到一个与你的机器行为不同的安装，没有明显的原因。删除你未使用的那个。

按框架的设置

这些是每个框架所需的值。如果 Orbit 为该框架提供了启动模板，模板将使用这些确切的设置。

框架	构建命令	输出目录	服务器模式
Next.js，静态导出	`npm run build`	`out`	关闭
Next.js，SSR 或 ISR	`npm run build`	`.next`	启用
Astro，静态	`astro build`	`dist`	关闭
Astro，服务器或混合	`astro build`	`dist`	启用
Vite（React、Vue、Svelte）	`npm run build`	`dist`	关闭
SvelteKit	`npm run build`	`build`	取决于适配器
Nuxt 3	`npm run build`	`.output`	启用
Remix	`npm run build`	`build`	启用
Express 或纯 Node API	`npm run build`	`dist`	启用
Create React App	`npm run build`	`build`	关闭
纯 HTML 或静态生成器	留空或你的生成器的命令	`.` 或它写入的文件夹	关闭

Vite 总是写入 dist，除非你在 vite.config.ts 中设置了 build.outDir。Astro 的输出文件夹在每种模式下都是 dist，模式之间变化的是你是否需要服务器模式，而不是文件落地的位置。

服务器模式

服务器模式是设置中运行时下的切换开关。启用它时，Orbit 会在每次部署后保持构建机器活跃运行 npm start，而不是提供静态文件夹。

对于带 SSR 的 Next.js、Remix、Nuxt、Express API 以及任何不是静态导出的东西，将其启用。对于真正的静态构建，将其关闭。

它从下一次部署开始应用，不适用于当前实时的部署。

缺少服务器模式的典型症状是一个网站，其中主页加载完美，但每个动态路由都返回 404。构建成功了，文件已发布，只是没有服务器运行来应答路由。如果你看到这种情况，启用服务器模式并重新部署，然后再改变其他任何东西。

Node.js 版本

在设置中的构建设置下设置 Node.js 版本。仅输入主版本号：18、20 或 22。留空使用平台默认值。

该版本适用于构建，以及启用服务器模式时的运行时。

显式固定版本，而不是依赖默认值。需要比默认值更新的 Node 的依赖会导致安装失败，并显示一个错误，该错误不会明显说明这一点，固定版本消除了整个"昨天还能工作"的构建失败类。

Monorepos

将根目录设置为包含应用的子目录，例如 apps/web。Orbit 在运行你的安装和构建命令之前会进入该目录。

它还做一些你想要但可能不期望的事情：仅改变该路径外文件的推送会自动跳过。一个有四个 Orbit 项目的 monorepo 因此只会重建提交实际触及的应用。

每个环境可以在设置中的暂存：构建覆盖下单独覆盖根目录，这在暂存构建不同工作区时很有用。

自定义构建设置

在设置中的构建设置下覆盖任何东西：

字段	示例	说明
安装命令	`npm ci`	或 `yarn install --frozen-lockfile`、`pnpm install --frozen-lockfile`
构建命令	`npm run build:prod`	完全按照书写方式运行
输出目录	`dist/client`	构建后发布的文件夹
根目录	`apps/frontend`	Monorepo 子目录
Node.js 版本	`20`	仅主版本

留空意味着自动检测。在"构建设置"卡上单击保存以应用。

暂存可以在暂存：构建覆盖部分中独立覆盖这些中的任何一个。留空的字段继承项目级值，因此你可以仅更改暂存的构建命令，其他的保持不变。

构建缓存

Orbit 在 Liftoff 和 Apex 计划上的构建之间缓存 node_modules。使用缓存时，部署显示缓存命中徽章，安装阶段会短得多。没有缓存的构建显示冷启动。

要强制完整重新安装，打开设置，然后清除构建缓存，并确认。每个环境的下一次部署从头开始运行完整安装。这无法撤消，它之后的构建会很慢。

构建机器资源

构建机器大小取决于你的计划，这对大型构建很重要：

计划	vCPU	RAM	磁盘	时间限制
Launch	1	1 GB	4 GB	30 分钟
Liftoff	2	2 GB	8 GB	30 分钟
Apex	4	4 GB	16 GB	30 分钟

用完内存或填满磁盘的构建会失败，失败类别命名在部署页面上。提高 NODE_OPTIONS=--max-old-space-size 只对机器的实际 RAM 有帮助。

从模板开始

如果你想在拥有存储库之前进行工作部署，请使用启动模板。在新建项目中，从导入 Git Repo 切换到从模板开始并选择一个：Next.js with shadcn/ui、Astro 营销网站、Remix Indie Stack、SvelteKit 启动器、最小 Nuxt 3 应用或 Express REST API。Orbit 复制模板，应用正确的构建设置，并部署它。