--- title: 從原始碼部署 description: 直接上傳 JavaScript 專案，不需要 Dockerfile。Agent Lab 會偵測框架、自動建置，做成網頁或 App。 url: https://agentlab.cresclab.com/docs/zh-tw/deploy/source-build language: zh-Hant-TW updated: 2026-10-08 --- # 從原始碼部署 直接上傳 JavaScript 專案，不需要 Dockerfile。Agent Lab 會偵測框架、自動建置，做成網頁或 App。 ## 會發生什麼事 把專案壓成 zip，`package.json` 放在最上層，然後上傳。平台會讀取專案、產生建置計畫並建置： - 只產出瀏覽器檔案的專案會變成**網頁**，由 CDN 提供。單頁應用的路徑（例如 `/orders/42`）都會回應 `index.html`。 - 會執行伺服器的專案會變成**容器 App**，建成映像檔後以非 root 使用者在 8080 埠執行。 你不需要寫 Dockerfile。如果專案最上層已經有 Dockerfile，會優先使用它；要關掉這個行為，請見[建置設定](https://agentlab.cresclab.com/docs/zh-tw/deploy/source-build.md#build-settings)。 > [!TIP] 這些不要放進 zip > `node_modules`、`.git`、`dist` 和 `.env`。平台會自己安裝套件，就算放了也會略過。 ## 支援的框架 | 會變成網頁 | 會變成 App | | ----------------------------------------------------- | ---------------------------------------------------- | | 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。 ## 環境變數 建置計畫會列出程式讀取的變數（來自 `.env.example`、`process.env.*`、`import.meta.env.*`），並標出看起來像機密、或建置時就需要的變數（例如 `VITE_*`、`NEXT_PUBLIC_*`）。 1. 部署前先填好：App 填在 **設定 › 執行設定**（機密放在 **機密**），網頁填在 **設定 › 建置變數**。從原始碼建置的版本，會列出程式有讀取但還沒設定的變數。 2. 變數也會傳給建置：建置時期的變數會被寫進網頁裡，所以絕對不要把機密放在 `VITE_` 或 `NEXT_PUBLIC_` 變數。 3. 機密會以掛載的方式提供給安裝與建置步驟（例如私有套件庫的權杖），不會寫進映像檔。 ## 建置設定 偵測猜錯時，可在 **設定 › 建置設定** 覆寫。空白的欄位會自動偵測。 | 設定 | 範例 | 變數 | | ----------------------- | --------------------- | -------------------------- | | 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` | | App 路徑 | `apps/web` | — | 在分支執行設定裡設定同名變數，會優先於建置設定。`ALPACK_*` 變數只影響建置，不會傳給執行中的 App。 被偵測為網頁的專案，只要設定啟動指令，就會變成 App。 ## Monorepo 一個 repository 裡有多個專案時，請上傳整個 repository，並在建置設定的 **App 路徑** 填入 App 所在的資料夾，例如 `apps/web`。平台會在這個資料夾裡偵測與建置，所以由這個資料夾自己的 `package.json` 和 lockfile 決定怎麼建置。目前還不能使用 repository 其他位置的套件，例如 `workspace:*` 相依。 ## 建置失敗時 | 看到的訊息 | 處理方式 | | -------------------------- | --------------------------------------------------------- | | 無法判斷如何建置這份原始碼 | 把 `package.json` 放在 zip 最上層，或設定啟動指令。 | | 建置沒有產出任何檔案 | 把輸出目錄設成建置實際寫出檔案的位置。 | | App 上傳的內容只是網頁 | App 不能變回網頁。請另外建立一個 App，或設定啟動指令。 | | 原生模組編譯失敗 | 請提交 lockfile；平台偵測到原生套件時會自動加入編譯工具。 | 版本頁面的建置記錄會列出每個步驟。用 AI 工具時，可以先請它取得建置計畫，見 [MCP 工具](https://agentlab.cresclab.com/docs/zh-tw/deploy/mcp-tools.md#sites)。