部署 Node.js 專案

Zeabur 支援眾多類型的 Node.js 專案：

原生專案 (支援 NPM/Yarn/PNPM/Bun 等套件管理器)
使用 Vite 打包的專案
Qwik
Next.js
Remix
Nuxt.js
Umi
Svelte (Kit)
Nest.js
Nue.js
Express
Astro
Waku
Nue
Create React App
vue-cli
Hexo
Vitepress
Astro (Static, SSR)
Slidev
Docusaurus
Solid Start (Node, Static)

Monorepo 支援

Zeabur 會自動辨識 pnpm workspace、Yarn Workspace 以及絕大多數基於這兩個 Monorepo 做法的工具鏈，如 Turborepo 和 Lerna 等。

以 Turborepo 的 basic 模板為例，它的 pnpm-workspace.yaml 內容為：

packages:
  - "apps/*"
  - "packages/*"

而 apps 下有 docs 及 web 兩個目錄。Zeabur 預設會挑選列在 workspace 套件清單中的第一個 Node.js 應用程式來部署，就以此例來說，Zeabur 會部署 apps/docs 這個應用程式。如果想要部署 apps/web，可以在專案的根目錄新增 zbpack.json 檔案，並加入以下內容：

{
    "app_dir": "apps/web"
}

或者是使用環境變數進行設定：

ZBPACK_APP_DIR=apps/web

這樣就會部署 apps/web 這個應用程式。

如果你的應用程式確實在根目錄，但使用 pnpm-workspace.yaml 放置 React 元件、設計系統等元素，你可以使用環境變數 ZBPACK_APP_DIR=/ 或在 zbpack.json 加入

{
    "app_dir": "/"
}

讓 Zeabur 部署你放在根目錄的應用程式。

Nx 和 Rush 等不以上述兩個作法為基礎的 Monorepo 方案尚未支援一鍵部署，可以先參考〈停用快取功能〉和〈更改編譯和啟動命令〉對 Monorepo 進行設定。

停用快取功能

預設 Zeabur 會調換安裝流程，透過記錄安裝依賴的步驟，加速你往後 CI/CD 的速度。一般的 Node.js 專案應該不受影響，但假如你的專案在安裝依賴時需要用到專案中的其他檔案而導致專案編譯失敗，你可能得停用快取功能才能正常使用。

在專案的根目錄新增 zbpack.json 檔案，並加入以下內容，即可停用這個功能。

{
    "cache_dependencies": false
}

或者是設定環境變數：

ZBPACK_CACHE_DEPENDENCIES=false

更改編譯和啟動命令

假如你的專案類型較為特殊（如使用自訂的 Monorepo 工具鏈），你可能會需要指定服務的編譯 (build) 和啟動 (start) 命令，比如將 frontend 服務的啟動命令改成 pnpm run start:frontend；把 api 服務的編譯命令改成 pnpm run start:api。

這裡介紹兩個更改這個命令的方式。

使用檔案修改

在 zbpack.json 加入以下兩個設定項目：

{
    "build_command": "<自訂編譯命令>",
    "start_command": "<自訂啟動命令>"
}

預設 zbpack.json 的設定會套用到所有部署的服務。如果你想限定「服務名稱為 api 的使用某個命令；服務名稱為 frontend 的使用另一個命令」，則需要建立 zbpack.[服務名稱].json 的檔案：

// zbpack.api.json
{
    "build_command": "pnpm run build:api",
    "start_command": "pnpm run start:api"
}

// zbpack.frontend.json
{
    "build_command": "pnpm run build:frontend",
    "start_command": "pnpm run start:frontend"
}

zbpack.json 的套用優先級是 zbpack.[服務名稱].json 大於 zbpack.json。

使用環境變數修改

你也可以使用環境變數來設定編譯和啟動命令：

ZBPACK_BUILD_COMMAND=pnpm run build:api
ZBPACK_START_COMMAND=pnpm run start:api

指定 Node.js 和包管理器版本

Node.js 版本

預設情況下，Zeabur 會使用最新的 LTS Node.js 版本來建置你的項目。

如果你想使用不同的版本，你可以在 package.json 中指定：

{
    "engines": {
        "node": "18.1.0"
    }
}

套件管理器版本

預設情況下，Zeabur 會使用 yarn 來安裝你的專案依賴。

如果你想使用其他的套件管理器以及特定的版本，你可以在 package.json 中指定：

{
    "packageManager": "pnpm@8.0.0"
}

網頁爬取

Playwright 支援

如果你的 package.json 有宣告 playwright-chromium，Zeabur 會自動幫您準備好執行 Playwright 必要的環境。

注意 Playwright 應以 Headless 模式執行，通常預設就是如此。

Puppeteer 支援

如果你的 package.json 有宣告 puppeteer，Zeabur 會自動幫您準備好執行 Puppeteer 必要的環境。

注意 Puppeteer 應以 Headless 模式執行，通常預設就是如此。

額外注意事項

監聽的 port 使用 process.env.PORT

例如：

const port = process.env.PORT || 3000
// 而非 const port = 3000

避免使用 nodemon 作為 runtime，開發完後，換成一般的 node 指令

例如 package.json 內：

{
    "scripts": {
        "start": "node server.js"
        // 而非 "start": "nodemon server.js"
    }
}

內網存取 Astro