sandbox_build

跑安裝或編譯步驟並保存輸出；輸入相同的箱子幾秒就還原，不用重新 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，幾秒而不是幾分鐘）。只裝相依的步驟（npm ci、pnpm install、yarn、bun install，可以帶旗標、用 && 串起來），而且 out 全是 node_modules 資料夾時，dir 最上層 package.json 與 package-lock.json 的 version 欄位不算進指紋，所以 bump 版號照樣重用；相依改了、workspace 子套件的版號改了還是算。安裝步驟不讀你的原始碼，把原始碼放進 exclude（["src"]），改程式就不會逼它重裝。noCache: true 照樣重編並換掉存著的產出。cached: true 表示這次編出來的產出已經存起來，之後的箱子可以直接拿；bytes 是存起來那包的大小。note 跟 sandbox_exec 一樣。

在箱子裡建置前端：

• Next.js 的 Turbopack 不接受指到專案外面的 node_modules symlink（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 結束，是撞到 Node 的 heap 上限，不是箱子的記憶體（size 1 就有 8 GB）：用 NODE_OPTIONS=--max-old-space-size=6144 調高；在容器裡建置時，再看它的 docker run --memory。
• 大型前端從 dev server 載入時，手機或慢的連線會很慢，因為瀏覽器要一個檔一個檔抓整個模組圖（大型 app 在 iPhone 上要好幾分鐘）。改成先建置一次、服務建出來的結果：vite build，再用 vite preview（或任何靜態伺服器）帶跟 dev server 一樣的 /api proxy，聽你宣告的 port。建置期的變數從環境的 .sh（. /work/.sbx/env/<服務>.sh）或 secrets 來（Secrets）；擋住建置的 required-build-env 檢查也這樣滿足，不要在 /work 留下金鑰檔。

所有工具與主題都列在工具參考。