如何用Java生成Google Cloud Storage文件夹的PUT签名URL以批量上传文件？

要实现生成允许向指定文件夹上传多个文件、且上传时可自定义文件名的PUT签名URL，核心思路是根据客户端指定的文件名实时生成对应对象路径的签名URL——因为GCS的PUT签名URL是与具体对象路径绑定的，无法直接生成通配符式的签名URL，但可以通过服务端动态生成每个目标文件的签名URL来满足需求。

步骤1：依赖准备 #

确保你的Java项目引入Google Cloud Storage客户端依赖（以Maven为例）：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage</artifactId>
    <version>2.28.0</version> <!-- 可替换为最新稳定版 -->
</dependency>

步骤2：核心实现代码 #

下面的示例代码会根据客户端传入的文件名，生成对应指定文件夹下对象的PUT签名URL，同时配置了简化客户端上传的参数：

import com.google.cloud.storage.*;
import java.net.URL;
import java.util.concurrent.TimeUnit;

public class GcsPutSignedUrlGenerator {
    // 初始化GCS客户端（默认使用环境变量或本地密钥文件认证）
    private static final Storage storage = StorageOptions.getDefaultInstance().getService();
    // 替换为你的Bucket名称
    private static final String BUCKET_NAME = "your-bucket-name";
    // 指定目标文件夹前缀（必须以斜杠结尾，确保文件都落在该前缀下）
    private static final String UPLOAD_FOLDER_PREFIX = "user-uploads/";

    /**
     * 生成指定文件夹下目标文件的PUT签名URL
     * @param clientFilename 客户端指定的文件名（需校验合法性，避免路径遍历）
     * @return 可直接用于PUT上传的签名URL
     */
    public static URL generatePutSignedUrl(String clientFilename) {
        // 校验客户端传入的文件名，防止路径遍历（如禁止../、/等字符）
        if (clientFilename.contains("../") || clientFilename.contains("/")) {
            throw new IllegalArgumentException("非法文件名，禁止包含路径分隔符");
        }

        // 拼接完整的GCS对象路径：文件夹前缀 + 客户端文件名
        String objectPath = UPLOAD_FOLDER_PREFIX + clientFilename;
        BlobInfo blobInfo = BlobInfo.newBuilder(BUCKET_NAME, objectPath).build();

        // 配置签名URL选项
        Storage.SignUrlOption[] options = {
            Storage.SignUrlOption.httpMethod(HttpMethod.PUT),
            Storage.SignUrlOption.expiration(1, TimeUnit.HOURS), // 签名URL有效期1小时
            Storage.SignUrlOption.withContentType(), // 允许客户端自定义Content-Type
            Storage.SignUrlOption.unusedPayload() // 允许客户端不提供内容哈希，简化上传逻辑
        };

        return storage.signUrl(blobInfo, 1, TimeUnit.HOURS, options);
    }

    // 测试示例
    public static void main(String[] args) {
        URL signedUrl = generatePutSignedUrl("profile-photo.jpg");
        System.out.println("PUT签名URL: " + signedUrl);
    }
}

步骤3：客户端使用（任意语言） #

拿到签名URL后，客户端只需发送PUT请求即可上传文件，无需依赖GCS SDK：

示例1：CURL命令 #

# 上传本地文件到指定路径
curl -X PUT -T "local-photo.jpg" -H "Content-Type: image/jpeg" "生成的签名URL"

示例2：Python请求 #

import requests

with open("local-photo.jpg", "rb") as f:
    response = requests.put("生成的签名URL", data=f, headers={"Content-Type": "image/jpeg"})
print(response.status_code)

关键注意事项 #

• 权限控制：生成签名的账号（通常是服务账号）需要拥有storage.objects.create权限，建议最小化权限，分配Storage Object Creator角色即可。
• 文件名校验：必须校验客户端传入的文件名，避免路径遍历攻击（比如客户端传入../private/data.txt会导致文件上传到非指定文件夹）。
• 有效期设置：根据业务需求调整签名URL的有效期，过长会增加安全风险，过短可能导致客户端上传超时。
• 认证方式：GCS客户端默认通过环境变量GOOGLE_APPLICATION_CREDENTIALS加载服务账号密钥文件，也可以在代码中显式指定密钥路径。

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