SDK 示例

下面给出几种常见语言的 S3 SDK 接入示例。示例中的参数请替换为七彩云对象存储实际分配的信息。

API 管理页面示意

图示说明：这是 API 管理页面示意。开始照着 SDK 示例写代码前，先确认你使用的 AccessKey、SecretKey、Bucket 和环境信息都是当前可用的。

通用参数

Endpoint   = <your-endpoint>
Region     = <your-region>
AccessKey  = <your-access-key>
SecretKey  = <your-secret-key>
Bucket     = <your-bucket>

可先跑通哪几个动作

无论你使用哪种语言，先优先验证：

列对象
上传小文件
下载文件
生成签名下载链接

先把这四步跑通，再接业务逻辑，排查会轻松很多。

Node.js（AWS SDK v3）

安装：

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

上传文件：

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import fs from 'node:fs';

const client = new S3Client({
  region: process.env.S3_REGION,
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
  forcePathStyle: false, // 如果你的接入要求是 Path Style，可改成 true
});

await client.send(
  new PutObjectCommand({
    Bucket: process.env.S3_BUCKET,
    Key: 'demo/hello.txt',
    Body: fs.readFileSync('./hello.txt'),
    ContentType: 'text/plain',
  }),
);

生成签名下载链接：

import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const client = new S3Client({
  region: process.env.S3_REGION,
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
  forcePathStyle: false,
});

const command = new GetObjectCommand({
  Bucket: process.env.S3_BUCKET,
  Key: 'demo/hello.txt',
});

const url = await getSignedUrl(client, command, { expiresIn: 300 });
console.log(url);

列对象：

import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: process.env.S3_REGION,
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
});

const result = await client.send(
  new ListObjectsV2Command({
    Bucket: process.env.S3_BUCKET,
    MaxKeys: 20,
  }),
);

console.log(result.Contents);

Node.js 最小闭环实战

下面这段脚本适合第一次接入时直接跑：

import {
  S3Client,
  PutObjectCommand,
  GetObjectCommand,
  ListObjectsV2Command,
} from '@aws-sdk/client-s3';
import {getSignedUrl} from '@aws-sdk/s3-request-presigner';

const client = new S3Client({
  region: process.env.S3_REGION,
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
  forcePathStyle: false,
});

await client.send(
  new PutObjectCommand({
    Bucket: process.env.S3_BUCKET,
    Key: 'demo/hello.txt',
    Body: Buffer.from('hello qicai from node'),
    ContentType: 'text/plain',
  }),
);

const list = await client.send(
  new ListObjectsV2Command({
    Bucket: process.env.S3_BUCKET,
    Prefix: 'demo/',
    MaxKeys: 20,
  }),
);

console.log('objects:', list.Contents?.map((item) => item.Key));

const signedUrl = await getSignedUrl(
  client,
  new GetObjectCommand({
    Bucket: process.env.S3_BUCKET,
    Key: 'demo/hello.txt',
  }),
  {expiresIn: 300},
);

console.log('signed url:', signedUrl);

Python（boto3）

安装：

pip install boto3

上传文件：

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='<your-endpoint>',
    region_name='<your-region>',
    aws_access_key_id='<your-access-key>',
    aws_secret_access_key='<your-secret-key>'
)

s3.upload_file('./hello.txt', '<your-bucket>', 'demo/hello.txt')

下载文件：

s3.download_file('<your-bucket>', 'demo/hello.txt', './hello.down.txt')

生成签名链接：

url = s3.generate_presigned_url(
    'get_object',
    Params={
        'Bucket': '<your-bucket>',
        'Key': 'demo/hello.txt'
    },
    ExpiresIn=300
)

print(url)

列对象：

result = s3.list_objects_v2(Bucket='<your-bucket>', MaxKeys=20)
print(result.get('Contents', []))

Python 最小闭环实战

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='https://s3.7caiyun.com',
    region_name='us-west',
    aws_access_key_id='<your-access-key>',
    aws_secret_access_key='<your-secret-key>'
)

bucket = '<your-bucket>'
key = 'demo/hello-python.txt'

s3.put_object(Bucket=bucket, Key=key, Body=b'hello qicai from python', ContentType='text/plain')

result = s3.list_objects_v2(Bucket=bucket, Prefix='demo/')
print('objects:', [item['Key'] for item in result.get('Contents', [])])

url = s3.generate_presigned_url(
    'get_object',
    Params={'Bucket': bucket, 'Key': key},
    ExpiresIn=300,
)
print('signed url:', url)

Go（AWS SDK v2）

安装：

go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/credentials
go get github.com/aws/aws-sdk-go-v2/service/s3
go get github.com/aws/aws-sdk-go-v2/feature/s3/manager

上传文件示例：

package main

import (
  "bytes"
  "context"
  "log"

  aws "github.com/aws/aws-sdk-go-v2/aws"
  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/aws/aws-sdk-go-v2/credentials"
  "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
  cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-west"),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("<your-access-key>", "<your-secret-key>", "")),
  )
  if err != nil {
    log.Fatal(err)
  }

  client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String("https://s3.7caiyun.com")
    o.UsePathStyle = false
  })

  _, err = client.PutObject(context.TODO(), &s3.PutObjectInput{
    Bucket:      aws.String("<your-bucket>"),
    Key:         aws.String("demo/hello-go.txt"),
    Body:        bytes.NewReader([]byte("hello qicai from go")),
    ContentType: aws.String("text/plain"),
  })
  if err != nil {
    log.Fatal(err)
  }
}

Go 最小闭环实战

package main

import (
  "bytes"
  "context"
  "fmt"
  "log"

  aws "github.com/aws/aws-sdk-go-v2/aws"
  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/aws/aws-sdk-go-v2/credentials"
  "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
  cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-west"),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("<your-access-key>", "<your-secret-key>", "")),
  )
  if err != nil {
    log.Fatal(err)
  }

  client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String("https://s3.7caiyun.com")
    o.UsePathStyle = false
  })

  bucket := "<your-bucket>"
  key := "demo/hello-go.txt"

  _, err = client.PutObject(context.TODO(), &s3.PutObjectInput{
    Bucket:      aws.String(bucket),
    Key:         aws.String(key),
    Body:        bytes.NewReader([]byte("hello qicai from go")),
    ContentType: aws.String("text/plain"),
  })
  if err != nil {
    log.Fatal(err)
  }

  list, err := client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{
    Bucket: aws.String(bucket),
    Prefix: aws.String("demo/"),
  })
  if err != nil {
    log.Fatal(err)
  }

  for _, item := range list.Contents {
    fmt.Println(*item.Key)
  }
}

Java（AWS SDK v2）

上传文件示例：

S3Client client = S3Client.builder()
    .region(Region.of("<your-region>"))
    .endpointOverride(URI.create("<your-endpoint>"))
    .credentialsProvider(
        StaticCredentialsProvider.create(
            AwsBasicCredentials.create("<your-access-key>", "<your-secret-key>")
        )
    )
    .forcePathStyle(false)
    .build();

PutObjectRequest request = PutObjectRequest.builder()
    .bucket("<your-bucket>")
    .key("demo/hello.txt")
    .contentType("text/plain")
    .build();

client.putObject(request, Paths.get("./hello.txt"));

Java 闭环骨架示例

S3Client client = S3Client.builder()
    .region(Region.of("us-west"))
    .endpointOverride(URI.create("https://s3.7caiyun.com"))
    .credentialsProvider(
        StaticCredentialsProvider.create(
            AwsBasicCredentials.create("<your-access-key>", "<your-secret-key>")
        )
    )
    .forcePathStyle(false)
    .build();

String bucket = "<your-bucket>";
String key = "demo/hello-java.txt";

client.putObject(
    PutObjectRequest.builder()
        .bucket(bucket)
        .key(key)
        .contentType("text/plain")
        .build(),
    RequestBody.fromString("hello qicai from java")
);

ListObjectsV2Response list = client.listObjectsV2(
    ListObjectsV2Request.builder()
        .bucket(bucket)
        .prefix("demo/")
        .build()
);

list.contents().forEach(item -> System.out.println(item.key()));

如果你要补完整私有下载，再接 S3Presigner。

PHP（AWS SDK for PHP）

上传文件示例：

use Aws\S3\S3Client;

$client = new S3Client([
    'version' => 'latest',
    'region' => '<your-region>',
    'endpoint' => '<your-endpoint>',
    'credentials' => [
        'key' => '<your-access-key>',
        'secret' => '<your-secret-key>',
    ],
    'use_path_style_endpoint' => false,
]);

$client->putObject([
    'Bucket' => '<your-bucket>',
    'Key' => 'demo/hello.txt',
    'SourceFile' => './hello.txt',
    'ContentType' => 'text/plain',
]);

生成签名下载链接：

$cmd = $client->getCommand('GetObject', [
    'Bucket' => '<your-bucket>',
    'Key' => 'demo/hello.txt',
]);

$request = $client->createPresignedRequest($cmd, '+5 minutes');
echo (string) $request->getUri();

PHP 最小闭环实战

use Aws\S3\S3Client;

$client = new S3Client([
    'version' => 'latest',
    'region' => 'us-west',
    'endpoint' => 'https://s3.7caiyun.com',
    'credentials' => [
        'key' => '<your-access-key>',
        'secret' => '<your-secret-key>',
    ],
    'use_path_style_endpoint' => false,
]);

$bucket = '<your-bucket>';
$key = 'demo/hello-php.txt';

$client->putObject([
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => 'hello qicai from php',
    'ContentType' => 'text/plain',
]);

$result = $client->listObjectsV2([
    'Bucket' => $bucket,
    'Prefix' => 'demo/',
]);

foreach ($result['Contents'] ?? [] as $item) {
    echo $item['Key'] . PHP_EOL;
}

$cmd = $client->getCommand('GetObject', [
    'Bucket' => $bucket,
    'Key' => $key,
]);

$request = $client->createPresignedRequest($cmd, '+5 minutes');
echo (string) $request->getUri() . PHP_EOL;

C#（AWS SDK for .NET）

上传文件示例：

using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

var config = new AmazonS3Config
{
    ServiceURL = "https://s3.7caiyun.com",
    ForcePathStyle = false,
    AuthenticationRegion = "us-west"
};

var client = new AmazonS3Client(
    new BasicAWSCredentials("<your-access-key>", "<your-secret-key>"),
    config
);

await client.PutObjectAsync(new PutObjectRequest
{
    BucketName = "<your-bucket>",
    Key = "demo/hello-csharp.txt",
    ContentBody = "hello qicai from csharp",
    ContentType = "text/plain"
});

C# 最小闭环实战

using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

var config = new AmazonS3Config
{
    ServiceURL = "https://s3.7caiyun.com",
    ForcePathStyle = false,
    AuthenticationRegion = "us-west"
};

var client = new AmazonS3Client(
    new BasicAWSCredentials("<your-access-key>", "<your-secret-key>"),
    config
);

var bucket = "<your-bucket>";
var key = "demo/hello-csharp.txt";

await client.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = key,
    ContentBody = "hello qicai from csharp",
    ContentType = "text/plain"
});

var list = await client.ListObjectsV2Async(new ListObjectsV2Request
{
    BucketName = bucket,
    Prefix = "demo/"
});

foreach (var item in list.S3Objects)
{
    Console.WriteLine(item.Key);
}

var signedUrl = client.GetPreSignedURL(new GetPreSignedUrlRequest
{
    BucketName = bucket,
    Key = key,
    Expires = DateTime.UtcNow.AddMinutes(5)
});

Console.WriteLine(signedUrl);

真实测试补充说明

这页列出的常见 SDK 已经完成一轮真实接口测试。

本轮已确认真实通过的包括：

Node.js（AWS SDK v3）
Python boto3
Go SDK
Java SDK
PHP SDK
C# / .NET SDK

其中：

Node.js 已实测上传、列对象、预签名链接访问
Python boto3 已实测上传、列对象、下载、预签名链接访问
Go / Java / PHP / C# 已实测上传、列对象、下载

如果你在自己环境里遇到 RequestTimeTooSkewed 或 Node.js 预签名 403，优先先检查系统时间是否准确。

接入建议

优先从上传 / 下载 / 列表这三类基础操作开始
先在服务端跑通，再接前端业务
如果遇到兼容问题，先尝试切换 forcePathStyle 或对应 SDK 的 Path Style 选项
正式环境不要把 AccessKey / SecretKey 写死在源码里
建议把公共配置统一封装，避免多个地方各写一套参数

常见排查方向

如果 SDK 接入报错，可优先检查：

Region 是否与平台分配值一致
Endpoint 是否包含正确协议头（如 https://）
存储桶（Bucket）名称是否拼写正确
是否误用了公有 / 私有访问逻辑
本地系统时间是否准确
SDK 是否默认启用了与你当前环境不匹配的访问风格

通用参数​

可先跑通哪几个动作​

Node.js（AWS SDK v3）​

Node.js 最小闭环实战​

Python（boto3）​

Python 最小闭环实战​

Go（AWS SDK v2）​

Go 最小闭环实战​

Java（AWS SDK v2）​

Java 闭环骨架示例​

PHP（AWS SDK for PHP）​

PHP 最小闭环实战​

C#（AWS SDK for .NET）​

C# 最小闭环实战​

真实测试补充说明​

接入建议​

常见排查方向​

相关页面​

通用参数

可先跑通哪几个动作

Node.js（AWS SDK v3）

Node.js 最小闭环实战

Python（boto3）

Python 最小闭环实战

Go（AWS SDK v2）

Go 最小闭环实战

Java（AWS SDK v2）

Java 闭环骨架示例

PHP（AWS SDK for PHP）

PHP 最小闭环实战

C#（AWS SDK for .NET）

C# 最小闭环实战

真实测试补充说明

接入建议

常见排查方向

相关页面