Next.js

Zenavo 識別出的內容

package.json 中有 next 的儲存庫會由 zbpack 建置，識別為 Node.js，框架為 next.js：

步驟	指令
安裝	根據儲存庫中的鎖檔案使用 `npm install`、`pnpm install`、`yarn install` 或 `bun install`（沒有鎖檔案時用 `yarn`）
建置	`build` 指令碼，通常是 `next build`
啟動	`start` 指令碼，通常是 `next start`

Node.js 版本取自 package.json 中的 engines.node（未設定時為 22）。請提交鎖檔案，這樣安裝結果可復現，也會使用正確的套件管理器。

next start 在所有網路卡上監聽 $PORT（Zenavo 設為 8080），所以預設的應用不需要任何修改：

json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

部署

新增服務 → GitHub，選擇儲存庫和分支。
新增應用需要的變數（見下文），點選 下一步。
確認預覽顯示 nodejs 和 next.js，然後點選部署。
在網路分頁生成網域或繫結自己的網域。

環境變數

伺服器端 變數（路由處理函式、伺服器端元件、getServerSideProps 中的 process.env.DATABASE_URL）在應用執行時讀取：在變數分頁中設定，然後重新部署。
NEXT_PUBLIC_* 變數會被 next build 寫入 JavaScript 包，所以建置時就必須存在。變數分頁中的變數只提供給執行中的應用，所以這類變數要在設定 → 建置 → 建置參數 中設定，例如 NEXT_PUBLIC_API_URL=https://api.example.com，或者用 NEXT_PUBLIC_API_URL=${API_URL} 複用一個變數。沒有 Dockerfile 時它們也能傳入建置；見建置參數。
連接埠繫結網域後，網站自己的位址是 ZENAVO_<PORT>_URL，例如 ${ZENAVO_WEB_URL}。可以用它設定 NEXTAUTH_URL 之類的變數。

連線資料庫

在專案中新增 PostgreSQL，並在 Next.js 服務中引用它的變數：

DATABASE_URL=${POSTGRESQL_CONNECTION_STRING}

Prisma、Drizzle 和 pg 都接受這個 URL。資料庫遷移請在服務啟動時執行，因為建置時存取不到資料庫：predeploy 指令碼會在 start 之前執行。

json

"scripts": {
  "build": "next build",
  "predeploy": "prisma migrate deploy",
  "start": "next start"
}

用 `output: 'standalone'` 縮小映像檔

在 next.config.js 中設定 output: 'standalone' 後，next build 會把一個獨立執行的伺服器寫到 .next/standalone。zbpack 不會使用它，所以想要受益，需要新增 Dockerfile：

dockerfile

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
ARG NEXT_PUBLIC_API_URL
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production HOSTNAME=0.0.0.0
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

HOSTNAME=0.0.0.0 讓 standalone 伺服器在所有網路卡上監聽，連接埠來自 EXPOSE（這裡是 3000）。建置需要的每個變數，例如 NEXT_PUBLIC_API_URL，都要在 RUN npm run build 之前加一行 ARG，並在設定 → 建置 → 建置參數 中填寫值。

常見問題

現象	原因
建置失敗，提示 `JavaScript heap out of memory`	大型應用需要的記憶體超過建置預設分配的記憶體。在設定 → 建置 → 建置參數中新增 `NODE_OPTIONS=--max-old-space-size=4096`（使用自己的 Dockerfile 時，還要在建置階段加上 `ARG NODE_OPTIONS`），或者精簡建置。
`NEXT_PUBLIC_*` 的值在瀏覽器中是 `undefined`	它只存在於變數分頁。把它設為建置參數後重新部署。使用自己的 Dockerfile 時，還要在 `next build` 之前用 `ARG` 宣告它。
`next/image` 的圖片載入失敗	遠端圖片需要在 `next.config.js` 中設定 `images.remotePatterns`。
standalone 伺服器無法存取	`HOSTNAME` 不是 `0.0.0.0`，所以它只監聽容器的主機名。

Next.js ​

Zenavo 識別出的內容 ​

部署 ​

環境變數 ​

連線資料庫 ​

用 output: 'standalone' 縮小映像檔 ​