從原始碼部署
直接上傳 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 CLI | Next.js(設定 output: "export" 時會變成網頁) |
| Angular、靜態 Astro、有建置腳本的純 HTML | Nuxt、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,平台不認得的名稱也是。
- 部署前先填好:網頁服務填在 設定 › 執行設定(機敏值放在 機敏值 底下),網頁填在 設定 › 建置變數。從原始碼建置的版本,會列出程式有讀取但還沒設定的變數。
- 變數也會傳給建置:建置時期的變數會被寫進網頁裡,所以絕對不要把機敏值放在
VITE_或NEXT_PUBLIC_變數。 - 機敏值會以掛載的方式提供給安裝與建置步驟(例如私有套件庫的權杖),不會寫進映像檔。
建置設定#
偵測猜錯時,可在 設定 › 建置設定 覆寫。空白的欄位會自動偵測。
| 設定 | 範例 | 變數 |
|---|---|---|
| Node.js 版本 | 22 | ALPACK_NODE_VERSION |
| 安裝指令 | npm ci | ALPACK_INSTALL_CMD |
| 建置指令 | npm run build:prod | ALPACK_BUILD_CMD |
| 啟動指令 | node dist/server.js | ALPACK_START_CMD |
| 輸出目錄 | dist/browser | ALPACK_OUTPUT_DIR |
| 不使用專案的 Dockerfile | 開啟 | ALPACK_IGNORE_DOCKERFILE |
| 根目錄 Root Directory | apps/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 和其他服務的憑證要另外設定;映像檔建置成功,不代表這些連線已經驗證過。