Crescendo Lab 文件
正體中文
註冊開始用

從原始碼部署

直接上傳 JavaScript、Go 或 Python 專案,不需要 Dockerfile。Agent Lab 會偵測框架、自動建置,做成網頁或網頁服務。

最後更新

會發生什麼事#

把專案壓成 zip,讓相依套件的 manifest 位在最上層,然後上傳。平台會讀取專案、產生建置計畫並建置:

  • 只產出瀏覽器檔案的專案會變成網頁,由 CDN 提供。單頁應用的路徑(例如 /orders/42)都會回應 index.html。
  • 會執行伺服器的專案會變成網頁服務,建成映像檔後以非 root 使用者在 8080 埠執行。

你不需要寫 Dockerfile。如果專案最上層已經有 Dockerfile,會優先使用它;要關掉這個行為,請見建置設定。

這些不要放進 zip

node_modules、.git、dist 和 .env。平台會自己安裝套件,就算放了也會略過。

支援的框架#

會變成網頁會變成網頁服務
Vite(React、Vue、Svelte)、Create React App、Vue CLINext.js(設定 output: "export" 時會變成網頁)
Angular、靜態 Astro、有建置腳本的純 HTMLNuxt、SvelteKit、Remix、React Router 7、SSR 的 Astro
Express、Fastify、Koa、Hono、NestJS 等 Node 伺服器

npm、pnpm、Yarn、Bun 會依 lockfile 或 packageManager 欄位判斷。Node.js 版本取自 engines.node、.nvmrc 或 .node-version,沒有寫就用最新 LTS(24)。可用版本為 18、20、22、24。

建置環境#

建置在完整的 node:<版本> 映像檔上執行,裡面有 git、python3、make、g++;服務本身則在較小的 node:<版本>-slim 上執行。安裝和建置步驟都能用 git,指令稿執行 git rev-parse HEAD 也拿得到結果:

  • 從 GitHub 建置時,拿到的是 push 的那個 commit(深度 1),所在 git 分支和 push 的 git 分支同名。
  • 上傳的原始碼會得到一個只有一個 commit 的 repository,內容就是上傳的檔案。上傳裡的 .git 資料夾不會使用。

建置期間有三個變數描述這個 commit:AGENTLAB_GIT_COMMIT_SHA、AGENTLAB_GIT_COMMIT_REF(git 分支)、AGENTLAB_GIT_REPO(owner/name)。從 GitHub 建置時才有值,上傳時是空的;你自己設定的同名變數會被忽略。這三個變數不會傳給執行中的服務。用自己 Dockerfile 的專案要用 ARG 宣告才會收到,而有沒有 git 要看你自己的映像檔。

環境變數#

建置計畫會列出程式讀取的變數(來自 .env.example、process.env.*、import.meta.env.*),並標出看起來像機敏值、或建置時就需要的變數(例如 VITE_*、NEXT_PUBLIC_*)。

Nuxt 3 以後的專案,也會讀 nuxt.config 裡 runtimeConfig 底下寫出的鍵:runtimeConfig.apiSecret 對應 NUXT_API_SECRET,runtimeConfig.public.apiBase 對應 NUXT_PUBLIC_API_BASE。有用 nuxt-auth-utils 時會列出 NUXT_SESSION_PASSWORD。用展開(...shared)加入、來自 layer 或其他模組的鍵找不到,請寫在 .env.example。

每個機敏值也會標出值由誰提供(source):

  • generate:只需要隨機、不必有人知道的值,例如 NUXT_SESSION_PASSWORD、SESSION_SECRET、AUTH_SECRET、SECRET_KEY_BASE。可以在主控台依框架要求的長度產生,或由助理透過 sites_secrets_generate 請平台產生並儲存,助理看不到值。
  • person:其他所有機敏值,例如 API 金鑰、webhook 的簽章密鑰、資料庫密碼,只有你知道值。名稱帶有 STRIPE_、LINE_ 這類服務名稱的一律是 person,平台不認得的名稱也是。
  1. 部署前先填好:網頁服務填在 設定 › 執行設定(機敏值放在 機敏值 底下),網頁填在 設定 › 建置變數。從原始碼建置的版本,會列出程式有讀取但還沒設定的變數。
  2. 變數也會傳給建置:建置時期的變數會被寫進網頁裡,所以絕對不要把機敏值放在 VITE_ 或 NEXT_PUBLIC_ 變數。
  3. 機敏值會以掛載的方式提供給安裝與建置步驟(例如私有套件庫的權杖),不會寫進映像檔。

建置設定#

偵測猜錯時,可在 設定 › 建置設定 覆寫。空白的欄位會自動偵測。

設定範例變數
Node.js 版本22ALPACK_NODE_VERSION
安裝指令npm ciALPACK_INSTALL_CMD
建置指令npm run build:prodALPACK_BUILD_CMD
啟動指令node dist/server.jsALPACK_START_CMD
輸出目錄dist/browserALPACK_OUTPUT_DIR
不使用專案的 Dockerfile開啟ALPACK_IGNORE_DOCKERFILE
根目錄 Root Directoryapps/web—

在環境的執行設定裡設定同名變數,會優先於建置設定。ALPACK_* 變數只影響建置,不會傳給執行中的服務。

被偵測為網頁的專案,只要設定啟動指令,就會變成網頁服務。

Monorepo#

一個 repository 裡有多個專案時,請上傳整個 repository,並在建置設定的 根目錄 Root Directory 填入專案所在的資料夾,例如 apps/web。平台會在這個資料夾裡偵測與建置,所以由這個資料夾自己的 package.json 和 lockfile 決定怎麼建置。目前還不能使用 repository 其他位置的套件,例如 workspace:* 相依。

新專案第一次上傳或 push 時,如果最上層沒有可以部署的東西(沒有 Dockerfile、沒有 package.json、go.mod、pyproject.toml、requirements.txt 或 setup.py,也沒有 index.html),但下一層或下兩層的資料夾裡有專案(例如分成 frontend/ 和 backend/ 的 repository),就不會發布。這個版本會列出最多五個資料夾,請你選擇要部署哪一個,專案類型也維持未決定。選好後會設定 根目錄 Root Directory 並重新部署:GitHub 會部署最新的 commit,主控台會部署同一份檔案。最上層有 index.html 的上傳內容仍然是網頁,即使旁邊的資料夾裡有原始碼。

建置失敗時#

看到的訊息處理方式
無法判斷如何建置這份原始碼把 package.json 放在 zip 最上層,或設定啟動指令。
建置沒有產出任何檔案把輸出目錄設成建置實際寫出檔案的位置。
網頁服務上傳的內容只是網頁網頁服務不能變回網頁。請另外建立一個專案,或設定啟動指令。
原生模組編譯失敗請提交 lockfile;建置用的映像檔已經有編譯工具(python3、make、g++)。

版本頁面的建置記錄會列出每個步驟。用 AI 工具時,可以先請它取得建置計畫,見 MCP 工具。

Go 與 Python#

把 go.mod、pyproject.toml、requirements.txt 或 setup.py 放在專案根目錄上傳。有 Dockerfile 時優先使用,沒有時自動產生。Go 會自動建置根目錄的 main package,或唯一的 cmd/*/main.go;有多個服務入口時,請指定建置和啟動指令。Python 支援 pip、Poetry、uv,以及 Django WSGI、Flask、FastAPI。其他入口請用 web: Procfile 或啟動設定指定。

Go 版本取自 go.mod;Python 依 .python-version、manifest 寫的 Python 範圍(支援 3.10–3.14)判斷,都沒指定時用 3.12。也可以用 ALPACK_GO_VERSION、ALPACK_PYTHON_VERSION 直接覆寫。ALPACK_PORT 指定自動產生的映像檔使用的通訊埠(1024–65535,預設 8080)。

需要系統函式庫時,用 ALPACK_BUILD_PACKAGES、ALPACK_RUNTIME_PACKAGES 設定以空白分隔的 Debian 套件名稱;建置工具只留在建置階段。原有的安裝、建置、啟動指令設定一樣適用。映像檔以非 root 執行,會保留程式的 assets,略過 Python cache 和虛擬環境。

原始碼單一檔案上限 128 MiB,解壓縮後總共最多 512 MiB、20,000 個檔案。資料庫、Redis 和其他服務的憑證要另外設定;映像檔建置成功,不代表這些連線已經驗證過。