Docker构建阶段Cloud Build连接Cloud SQL的NextJS部署问题

添加调用Prisma查询用户数量的API路由后，Cloud Build执行npm run build时出现数据库连接失败错误。原因是Cloud Build不在Cloud SQL的授权网络列表中，且Docker构建环境独立，外部配置的Cloud SQL代理无法在容器内生效；本地通过公网IP连接正常是因为家庭网络已被授权。

方案1：授权Cloud Build IP范围至Cloud SQL #

• 查找对应GCP区域的Cloud Build公网IP范围，将这些IP段添加到Cloud SQL实例的授权网络列表中
• 构建时直接使用公网IP格式的DATABASE_URL：

  DATABASE_URL=postgresql://<DB_USER>:<DB_PASSWORD>@<PUBLIC_IP>:<PORT>/<DB_NAME>
  

• 优缺点：配置简单，但依赖公网连接，需确保数据库密码足够安全，且需定期检查IP范围是否更新

方案2：在Docker构建阶段内嵌Cloud SQL代理 #

修改Dockerfile的构建阶段，集成Cloud SQL代理，确保构建时能通过代理连接数据库：

# 构建阶段
FROM node:20-alpine AS builder

# 安装依赖
WORKDIR /app
COPY package*.json ./
RUN npm ci

# 下载并配置Cloud SQL代理
RUN wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy && chmod +x cloud_sql_proxy

# 设置构建所需环境变量
ENV DATABASE_URL="postgresql://<DB_USER>:<DB_PASSWORD>@127.0.0.1:5432/<DB_NAME>"
# 替换为你的Cloud SQL连接名：项目ID:区域:实例名
ENV CLOUD_SQL_CONNECTION_NAME="your-project-id:us-central1:your-sql-instance"

# 启动代理并执行构建（后台启动代理后等待几秒确保连接就绪）
RUN ./cloud_sql_proxy -instances=${CLOUD_SQL_CONNECTION_NAME}=tcp:5432 & sleep 5 && npm run build

# 后续的运行阶段配置...

• 前提：为Cloud Build服务账号授予Cloud SQL Client角色，确保代理能访问数据库实例
• 优缺点：无需开放公网IP，但会增加构建时间和Docker镜像复杂度

方案3：避免构建阶段连接数据库（推荐） #

NextJS构建时会对API路由进行静态分析，若代码中存在数据库调用可能会在构建阶段触发。通过判断构建环境，跳过构建时的数据库操作：
修改API路由代码：

import { NextRequest, NextResponse } from "next/server";
import prisma from "@app/lib/prisma";

const handler = async (req: NextRequest) => {
  // 检测是否处于构建阶段，跳过数据库查询
  if (process.env.NEXT_PHASE === "phase-production-build") {
    return NextResponse.json({ count: 0 }, { status: 200 });
  }

  if (req.method === "GET") {
    const count = await prisma.user.findMany();
    return NextResponse.json({ count: count.length });
  }

  return NextResponse.json({ error: "Method not allowed" }, { status: 405 });
};

export { handler as GET };

• 原理：NEXT_PHASE是NextJS构建时自动设置的环境变量，构建阶段值为phase-production-build，运行时无此变量
• 优缺点：完全避免构建时依赖外部服务，符合NextJS最佳实践，无需修改网络或Docker配置

内容的提问来源于stack exchange，提问作者Anthony Tedesco