如何在NextJS 13路由处理器中流式传输GCP Cloud Storage私有文件

核心实现思路 #

通过NextJS API端点作为中间层，先完成用户身份验证，再从Cloud Storage拉取文件流并直接转发给客户端。该方案既保证仅授权用户可访问私有资源，又能通过自定义响应头恢复完整缓存能力，同时避免签名URL的性能损耗。

步骤1：安装依赖 #

npm install @google-cloud/storage
# 或使用yarn
yarn add @google-cloud/storage

步骤2：身份验证前置校验 #

在API路由开头加入身份验证逻辑，确保只有授权用户能进入后续流程。示例采用NextAuth的session验证：

import { getServerSession } from "next-auth/next";
import { authOptions } from "@/app/api/auth/[...nextauth]/route";

// 在API处理函数中执行验证
const session = await getServerSession(authOptions);
if (!session) {
  return new Response("Unauthorized", { status: 401 });
}

若使用自定义JWT验证，逻辑类似：解析请求头中的token并验证有效性即可。

步骤3：App Router流式传输API实现（NextJS 13+） #

在app/api/images/[filename]/route.ts创建路由文件：

import { Storage } from "@google-cloud/storage";
import { getServerSession } from "next-auth/next";
import { authOptions } from "@/app/api/auth/[...nextauth]/route";

// 初始化Cloud Storage客户端（Cloud Run环境自动使用服务账号权限）
const storage = new Storage();
const BUCKET_NAME = "your-private-bucket-name"; // 替换为你的私有桶名称

export async function GET(
  request: Request,
  { params }: { params: { filename: string } }
) {
  // 1. 验证用户身份
  const session = await getServerSession(authOptions);
  if (!session) {
    return new Response("Unauthorized", { status: 401 });
  }

  const filename = params.filename;
  const bucket = storage.bucket(BUCKET_NAME);
  const file = bucket.file(filename);

  // 2. 检查文件是否存在
  const [exists] = await file.exists();
  if (!exists) {
    return new Response("File not found", { status: 404 });
  }

  // 3. 获取文件元数据，用于设置响应头
  const [metadata] = await file.getMetadata();

  // 4. 拉取文件流并转发给客户端
  const fileStream = file.createReadStream();

  // 配置缓存策略（可根据业务调整max-age时长）
  const headers = new Headers({
    "Content-Type": metadata.contentType || "application/octet-stream",
    "Cache-Control": "public, max-age=31536000, immutable",
    "Content-Length": metadata.size?.toString() || "",
  });

  return new Response(fileStream, { headers, status: 200 });
}

步骤4：Pages Router兼容实现（可选） #

若使用Pages Router，在pages/api/images/[filename].ts中实现：

import { Storage } from "@google-cloud/storage";
import { getServerSession } from "next-auth/next";
import { authOptions } from "../auth/[...nextauth]";
import type { NextApiRequest, NextApiResponse } from "next";

const storage = new Storage();
const BUCKET_NAME = "your-private-bucket-name";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const session = await getServerSession(req, res, authOptions);
  if (!session) {
    res.status(401).send("Unauthorized");
    return;
  }

  const { filename } = req.query;
  if (typeof filename !== "string") {
    res.status(400).send("Invalid filename");
    return;
  }

  const bucket = storage.bucket(BUCKET_NAME);
  const file = bucket.file(filename);

  const [exists] = await file.exists();
  if (!exists) {
    res.status(404).send("File not found");
    return;
  }

  const [metadata] = await file.getMetadata();

  // 设置响应头
  res.setHeader("Content-Type", metadata.contentType || "application/octet-stream");
  res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
  res.setHeader("Content-Length", metadata.size?.toString() || "");

  // 流式传输文件到客户端
  file.createReadStream().pipe(res);
}

关键优化与注意事项 #

• 同区域部署：确保Cloud Run服务与Cloud Storage桶处于同一GCP区域，最小化跨区域延迟。
• 服务账号权限：为Cloud Run的服务账号分配roles/storage.objectViewer权限，保证能读取私有桶内文件。
• 缓存策略：使用immutable指令可避免客户端重复验证缓存有效性，进一步提升性能。
• 异常处理：建议补充文件读取失败、权限不足等异常捕获逻辑，返回对应HTTP状态码。
• 内存优化：直接转发流而非将整个文件加载到内存，降低Cloud Run实例的内存占用。

内容的提问来源于stack exchange，提问作者Nathan Bedford