---
title: "@aws-sdk/client-s3: настройка и работа с S3-совместимым хранилищем в JavaScript"
description: "Подробное руководство по работе с @aws-sdk/client-s3: установка, настройка доступа, подключение к S3-совместимому Object Storage, загрузка, скачивание, просмотр и удаление объектов. Документация Timeweb Cloud."
---

# JavaScript

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

`[@aws-sdk/client-s3](https://www.npmjs.com/package/@aws-sdk/client-s3)` — это официальная библиотека AWS SDK для работы с сервисом S3 на языке JavaScript. С ее помощью можно загружать и скачивать файлы, получать списки объектов, удалять их, использовать мультипарт-загрузку и формировать подписанные ссылки.

## Установка

Для установки используйте `npm` или `yarn`:

```
npm install @aws-sdk/client-s3
```

или

```
yarn add @aws-sdk/client-s3
```

## Настройка доступа

При использовании `@aws-sdk/client-s3` реквизиты доступа можно задать несколькими способами.

### Через файлы `~/.aws/config` и `~/.aws/credentials`

При использовании [AWS CLI](https://timeweb.cloud/docs/s3-storage/tools/aws-cli) в домашней директории пользователя автоматически создается папка `.aws` с файлами, содержащими данные для подключения к S3. При необходимости эту папку и файлы можно создать вручную — без использования AWS CLI. Файл `~/.aws/credentials` должен содержать такие данные:

```
[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_KEY>
```

И `~/.aws/config`:

```
[default]
output = json
endpoint_url = https://s3.twcstorage.ru
region = ru-1
```

### Через переменные окружения

Реквизиты можно задать с помощью переменных окружения:

```
export AWS_ACCESS_KEY_ID=<ACCESS_KEY>
export AWS_SECRET_ACCESS_KEY=<SECRET_KEY>
```

### Через код приложения

Полная настройка клиента с явной передачей всех параметров:

```js
const { S3Client } = require("@aws-sdk/client-s3");

const s3 = new S3Client({
  region: "ru-1",
  endpoint: "https://s3.twcstorage.ru",
  credentials: {
    accessKeyId: "<ACCESS_KEY>",
    secretAccessKey: "<SECRET_KEY>"
  }
});
```

### Использование профиля AWS CLI

Если настроено несколько профилей, можно указать нужный через переменную окружения:

```
export AWS_PROFILE=myprofile
```

В этом случае можно создать клиента без передачи ключей:

```js
const s3 = new S3Client({
  region: "ru-1",
  endpoint: "https://s3.twcstorage.ru"
});
```

## Пример

Рассмотрим, как при помощи SDK выполнять базовые операции с объектами. В этом примере скрипт:

-   загружает файл в бакет;
-   выводит список всех объектов;
-   скачивает загруженный файл под другим именем;
-   удаляет объект из хранилища.

Предварительно создайте файл с именем `example.txt` в той же директории, где находится скрипт.

Код скрипта:

```js
const {
  S3Client,
  ListObjectsV2Command,
  PutObjectCommand,
  GetObjectCommand,
  DeleteObjectCommand
} = require("@aws-sdk/client-s3");

const { createReadStream, createWriteStream, existsSync } = require("fs");
const { pipeline } = require("stream");
const { promisify } = require("util");

const pipe = promisify(pipeline);

const bucketName = "имя_бакета";
const region = "ru-1";
const endpoint = "https://s3.twcstorage.ru";
const localUploadPath = "example.txt";
const s3Key = "example.txt";
const localDownloadPath = "downloaded_example.txt";

// Создание клиента S3
const s3 = new S3Client({
  region,
  endpoint,
});

async function main() {
  // 1. Загрузка файла
  if (existsSync(localUploadPath)) {
    console.log(`Загрузка файла ${localUploadPath} в бакет...`);
    await s3.send(new PutObjectCommand({
      Bucket: bucketName,
      Key: s3Key,
      Body: createReadStream(localUploadPath),
    }));
    console.log("Загрузка завершена.");
  } else {
    console.log(`Файл ${localUploadPath} не найден. Пропуск загрузки.`);
  }

  // 2. Список объектов
  console.log("\nСодержимое бакета:");
  const list = await s3.send(new ListObjectsV2Command({ Bucket: bucketName }));
  (list.Contents || []).forEach((obj) => {
    console.log(`- ${obj.Key}`);
  });

  // 3. Скачивание
  console.log(`\nСкачивание ${s3Key} в ${localDownloadPath}...`);
  const { Body } = await s3.send(new GetObjectCommand({
    Bucket: bucketName,
    Key: s3Key,
  }));
  if (Body) {
    await pipe(Body, createWriteStream(localDownloadPath));
    console.log("Скачивание завершено.");
  }

  // 4. Удаление
  console.log(`\nУдаление ${s3Key} из бакета...`);
  await s3.send(new DeleteObjectCommand({ Bucket: bucketName, Key: s3Key }));
  console.log("Удаление завершено.");
}

main().catch((err) => {
  console.error("Ошибка при выполнении операций:", err);
});
```

Дополнительные примеры использования SDK вы можете найти в [нашем репозитории GitHub](https://github.com/timeweb-cloud/s3-examples/tree/master/nodejs).