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' 缩小镜像 ​