配置您的构建命令和输出目录

Getting Orbit to build your project correctly comes down to a handful of fields in Settings: install command, build command, output directory, root directory and Node.js version. Left blank they are…

配置你的构建命令和输出目录

让 Orbit 正确构建你的项目取决于 Settings 中的几个字段: 安装命令、构建命令、输出目录、根目录和 Node.js 版本。留空时它们会被自动检测，大多数首次部署问题来自于自动检测的值与你的框架实际写入的内容不匹配。

在哪里找到这些设置

在 Orbit 中打开你的项目，转到 Settings 选项卡，找到 Build settings 卡片。

字段	作用	留空时的占位符
Install command	在构建前如何安装依赖	`npm ci (auto-detected)`
Build command	生成输出的命令	`npm run build (auto-detected)`
Output directory	Orbit 在构建后发布的文件夹	`dist (auto-detected)`
Root directory	对于 monorepos，包含你的应用的子目录	`/ (monorepo subdirectory)`
Node.js version	用于构建和运行的 Node 主版本号	Platform default

留空任何字段以让 Orbit 自动检测。点击 Build settings 卡片上的 Save 按钮应用设置。

Orbit 项目设置中的 Build settings 卡片

修改构建设置不会改变当前在线的部署。新设置从 下一次部署 开始应用。保存后重新部署，否则似乎什么都没有发生。

框架默认值

Next.js

Next.js 在 Orbit 中有两种模式，选择错误的是最常见的首次部署错误。

静态导出（output: 'export' 在 next.config.js 中）:

构建命令: npm run build
输出目录: out
Server mode: off

Server mode (SSR or ISR)，这是大多数 Next.js 应用:

在 Settings 中的 Runtime 下启用 Server mode
构建命令: npm run build
输出目录: .next

如果未启用 server mode，服务器渲染的 Next.js 应用会被发布为静态文件。主页通常会加载，但每个动态路由都会返回 404。如果这是你的症状，这就是原因：启用 server mode 并重新部署，不要改变其他任何东西。

Astro

Astro 的输出文件夹在每种模式下都是 dist。改变的是你是否需要 server mode。

output: 'static'，默认值: 输出目录 dist，server mode off
output: 'server' 或 output: 'hybrid': 输出目录 dist，server mode on
构建命令: npm run build，或 astro build

Vite (React, Vue, Svelte)

构建命令: npm run build，或 vite build
输出目录: dist

Vite 总是写入 dist，除非你在 vite.config.ts 中覆盖了 build.outDir。如果你有，将输出目录设置为匹配。

SvelteKit

构建命令: npm run build
输出目录: build

你是否需要 server mode 取决于你的适配器：静态适配器不需要，Node 适配器需要。

Nuxt 3

构建命令: npm run build
输出目录: .output
Server mode: on

Remix

构建命令: npm run build
输出目录: build
Server mode: on

Express 或纯 Node API

构建命令: npm run build
输出目录: dist
Server mode: on

Server mode 在构建后运行 npm start，所以确保你的 start 脚本存在并启动服务器。

Create React App

Create React App 已在上游被弃用，不是新项目的好选择，但现有项目可以正常构建。

构建命令: npm run build
输出目录: build

纯 HTML 或静态站点生成器

如果没有 package.json，留空安装命令
留空构建命令以按原样发布存储库，或设置你的生成器命令
输出目录: . 用于存储库根目录，或生成器写入的任何文件夹

Node.js 版本

仅输入 主版本号：18、20 或 22。字段提示明确表示如此。任何其他内容，如 20.11.0 或 v20，都不是此字段期望的。

该版本适用于构建，当 server mode 打开时，也适用于运行时。

固定版本而不是依赖默认值。需要较新 Node 的依赖在安装时会失败，出现很少直言"错误的 Node 版本"的错误，固定版本可以完全消除这类失败。

Monorepos

将 Root directory 设置为你的应用的路径，例如 apps/web。Orbit 在运行你的安装和构建命令前会切换到该目录，输出目录则相对于它。

字段提示说明了第二个更有用的行为：推送会自动跳过该路径之外的文件。一个拥有四个 Orbit 项目的 monorepo 只会重建提交实际触及的应用，这可以节省时间和构建分钟数。

每个环境可以独立覆盖根目录，在 Settings 中的 Staging: build overrides 下，这在 staging 构建不同工作区时很有用。

Staging 覆盖

如果你的项目有一个 staging 环境，Settings 会显示一个 Staging: build overrides 部分，字段相同。任何在那里留空的字段都会继承项目级的值，所以你可以只为 staging 更改构建命令，例如改为 npm run build:staging，并将其他一切保留不变。

Staging 在附近还有自己的相关设置：一个分支、一个访问密码、一个 IP 允许列表、失败时自动回滚，以及一个 Inherit production env vars 开关。

构建缓存

Orbit 在 Liftoff 和 Apex 计划上的构建之间缓存 node_modules。部署详情页面显示 Cache hit 或 Cold build，以及安装阶段的持续时间，所以你可以看到缓存在你项目上的价值。

要强制完全重新安装，打开 Settings，点击 Clear build cache，然后确认。

清除构建缓存不能撤销，每个环境的下一次部署都会从头开始完整安装。在大型 monorepo 上这是一个缓慢的构建，所以要有意而为之，而不是作为反射。

常见陷阱

"构建成功但网站显示 404。" 输出目录错误：Orbit 发布了不是你构建输出的文件夹。检查你的构建实际创建的文件夹。Vite 写入 dist，Next.js 静态导出写入 out，Next.js server mode 使用 .next，Create React App 和 Remix 写入 build，Nuxt 写入 .output。

"仅在动态路由上显示 404，主页很好。" Server mode 在需要它的应用上被关闭。见上面的 Next.js 部分。

"Module not found"在首次部署时。 要么安装步骤没有运行，要么它用与你本地使用的不同的包管理器运行。显式设置安装命令：npm ci、yarn install --frozen-lockfile 或 pnpm install --frozen-lockfile。还要检查你只提交了一个 lockfile：如果 package-lock.json 和 yarn.lock 都在存储库中，检测到的包管理器可能不是你期望的。

"Lockfile 过期。" npm ci 和冻结锁定文件等价物在 lockfile 与 package.json 不一致时拒绝运行。在本地运行你的包管理器的安装并提交重新生成的 lockfile。这是最常见的首次部署失败，它永远不会在本地重现，这正是为什么它令人困惑。

"我的 monorepo 中只有一个应用在部署。" 那是根目录在做它的工作。每个应用都需要自己的 Orbit 项目和自己的根目录。

"错误的 Node.js 版本。" 将 Node.js 版本字段设置为仅主版本号。

构建耗尽内存或填满磁盘。 两者都是构建机器上的计划限制：Launch 获得 1 vCPU、1 GB RAM 和 4 GB 磁盘；Liftoff 获得 2、2 GB 和 8 GB；Apex 获得 4、4 GB 和 16 GB。添加 NODE_OPTIONS=--max-old-space-size=2048 作为环境变量最多只有助于机器的实际 RAM。见 Orbit 计划限制。