部署 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（静态、SSR）
Slidev
Docusaurus
Solid Start（Node、静态）

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