Todos os produtos
Search

Este produto

    :Inicialização (SDK para Node.js)

    Central de documentação

    :Inicialização (SDK para Node.js)

    Última atualização: Jul 03, 2026

    O Client é o ponto de entrada principal do SDK do OSS para Node.js e gerencia recursos do OSS, como buckets e objetos. Para enviar solicitações ao OSS, inicialize uma instância de Client e, opcionalmente, personalize a configuração padrão.

    Observações de uso

    Pré-requisitos

    Importante

    Antes de configurar o cliente, defina as variáveis de ambiente com o AccessKey de um usuário do RAM.

      Exemplos de configuração padrão

      Os exemplos de código a seguir mostram como configurar uma instância do OSSClient com Signature V4 e Signature V1.

      Signature V4 (recomendado)

      Importante

      • Ao inicializar uma instância do OSSClient com o algoritmo Signature V4, especifique o ID da região específico do OSS. Esse ID identifica a região de destino da solicitação. Por exemplo, para a região China (Hangzhou), defina Region como oss-cn-hangzhou. Para outros IDs de região, consulte Regiões e endpoints.

      • Declare explicitamente o uso do algoritmo Signature V4 no código. Exemplo: authorizationV4: true.

      O código abaixo exemplifica a configuração de uma instância do OSSClient com um nome de domínio do OSS e Signature V4.

      Este exemplo demonstra a inicialização do cliente usando variáveis de ambiente para credenciais e um endpoint público.

      const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the public endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

      Signature V1 (não recomendado)

      Importante

      O código a seguir configura uma instância do OSSClient com um nome de domínio do OSS. Para informações sobre nomes de domínio do OSS em diferentes regiões, consulte Regiões e endpoints.

      Criar uma instância de Client com um nome de domínio do OSS

      O código a seguir mostra como inicializar uma instância com um nome de domínio do OSS.

      const OSS = require('ali-oss');

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
});

      Criar uma instância de Client com um nome de domínio personalizado

      O código a seguir mostra como criar uma instância de Client com um nome de domínio personalizado. Para mais informações sobre acesso ao OSS com nome de domínio personalizado, consulte Acessar o OSS usando um nome de domínio personalizado.

      Importante

      Não é possível usar o método client.listBuckets() com um nome de domínio personalizado.

      const OSS = require('ali-oss')

const client = new OSS({  
 // Use a custom domain name as the endpoint.
 endpoint: 'http://img.example.com', 
 // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // Set bucket to the name of your bucket.
 bucket: 'yourBucketName',
});

      Exemplos de configuração para casos de uso comuns

      Os exemplos de código a seguir mostram como configurar outros nomes de domínio. Por padrão, esses exemplos utilizam Signature V4 e as informações de AccessKey de um usuário do RAM.

      Exemplo de configuração de nome de domínio interno

      Se a aplicação estiver implantada em uma instância do Alibaba Cloud ECS e precisar acessar frequentemente recursos do OSS na mesma região, utilize um nome de domínio interno para reduzir custos de tráfego e melhorar a velocidade de acesso.

      O código a seguir apresenta um exemplo de configuração de uma instância do OSSClient com um nome de domínio interno do OSS.

      const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the internal endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou-internal.aliyuncs.com.
  endpoint: 'yourEndpoint',
});

      Exemplo de configuração de nome de domínio personalizado

      O código a seguir ilustra a configuração de uma instância do OSSClient com um nome de domínio personalizado.

      Aviso

      Vincule previamente o nome de domínio personalizado ao nome de domínio padrão do bucket. Caso contrário, ocorrerá um erro. Para mais detalhes sobre como vincular um nome de domínio personalizado, consulte Acessar o OSS usando um nome de domínio personalizado.

      const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to your custom domain name. For example, https://static.example.com.
  endpoint: 'yourEndpoint',
  // Set cname to true to enable the CNAME option.
  cname: true,
});

      Exemplo de configuração de endpoint de aceleração

      O trecho de código abaixo demonstra como configurar uma instância do OSSClient com um endpoint de aceleração.

      const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to an acceleration endpoint. For example, oss-accelerate.aliyuncs.com.
  endpoint: 'oss-accelerate.aliyuncs.com',
});

      Referências

      Para mais informações sobre as opções de configuração do OSSClient, consulte Exemplos no GitHub.