sandbox_build

インストールやコンパイルの手順を実行して出力を保存します。入力が同じボックスは、ビルドし直さずに数秒で復元します。

dir でインストールやコンパイルを実行し、その出力を保存します。dir は /work からの相対（app。/work/app でも可）、out と exclude は dir からの相対です：{ "dir": "app", "cmd": "npm ci", "out": ["node_modules"] }（/work/app/dist のような dir 内の絶対パスでも可）。フィンガープリントは dir の内容（node_modules などの派生ディレクトリと exclude に挙げたパスを除く）、cmd、env、ツールチェーンのバージョンから作られます。同じフィンガープリントを以前にビルドしていれば、out のパスをそのまま復元します（reused: true、数分ではなく数秒）。out が node_modules フォルダーだけのインストール手順（npm ci、pnpm install、yarn、bun install。フラグ付きや && でつないだものも可）では、dir の一番上の package.json と package-lock.json の version フィールドをフィンガープリントに含めないので、バージョンを上げても再利用されます。依存の変更とワークスペースのパッケージのバージョンは引き続き含まれます。インストール手順はソースを読まないので、ソースを exclude に入れれば（["src"]）、編集しても再インストールにはなりません。noCache: true なら必ずビルドし、保存済みの出力を置き換えます。cached: true は今回の出力が保存され、以降のボックスで再利用できることを示します。bytes は保存した出力のサイズです。note は sandbox_exec と同じです。

ボックスでフロントエンドをビルドするとき：

• Next.js の Turbopack は、プロジェクトの外を指す node_modules のシンボリックリンクを受け付けません（Symlink node_modules is invalid, it points out of the filesystem root）。sandbox_build で node_modules をプロジェクト内に復元するか（out: ["node_modules"]）、リンクではなく cp -a でコピーしてください。
• 大きな Vite や webpack のビルドが JavaScript heap out of memory で止まるのは、ボックスのメモリ（サイズ 1 で 8 GB）ではなく Node のヒープ上限に当たったためです。NODE_OPTIONS=--max-old-space-size=6144 で上げ、コンテナでビルドしているなら docker run --memory も確かめます。
• 大きなフロントエンドを開発サーバーから読み込むと、ブラウザがモジュールグラフを 1 ファイルずつ取りに行くため、スマートフォンや遅い回線では時間がかかります（大きなアプリだと iPhone で数分）。一度ビルドして出力を配信してください：vite build のあと、開発サーバーと同じ /api プロキシを付けた vite preview（または任意の静的サーバー）を、宣言したポートで動かします。ビルド時の変数は環境の .sh（. /work/.sbx/env/<サービス>.sh）かシークレットから渡し（シークレット）、ビルドを止める required-build-env のチェックも同じ方法で満たします。キーのファイルを /work に残さないでください。

すべてのツールとトピックはツールリファレンスに並んでいます。