附录：共享 COS 桶（ExternalStorage）

单个腾讯云账号下的 COS 存储桶数量存在账号级配额上限。当平台需要在单账号下创建超过 150 个环境时，若每个环境都自动分配独立的 COS 桶，将触及该配额导致环境创建失败。

此时可在 CreateEnv 中传入 ExternalStorage，让多个环境共享同一个外部 COS 桶：环境不再自动分配独立桶，而是将指定桶挂载为该环境的云存储介质，并通过 BasePath 前缀实现环境间文件目录的隔离。

CreateEnv 中的 ExternalStorage 只作用于云存储。静态网站托管的存储桶单独配置，由平台在开通托管时分配，见静态托管使用共享桶。

ExternalStorage 字段说明

字段	必选	类型	说明
BucketName	是	String	共享的 COS 桶名称，例如 tcb-ext-stor-1257619089
Region	是	String	桶所在地域，例如 ap-shanghai
BasePath	是	String	基础路径。绑定后，用户访问云存储内文件时，后台会自动以 BasePath 作为前缀拼接，用于桶内目录隔离。同一个桶内各环境的 BasePath 需唯一，否则文件会互相覆盖
Enabled	否	Boolean	是否启用外部存储，传 true 即启用。建议显式传入 true，查询环境信息时即可按该字段识别共享桶环境（见确认生效）

仅在 Resources 中包含 storage 时该参数生效。

外部存储目前只支持腾讯云对象存储 COS，BucketName 填写 COS 存储桶名称即可，无需指定存储提供商。

调用示例

const tencentcloud = require("tencentcloud-sdk-nodejs");
const TcbClient = tencentcloud.tcb.v20180608.Client;

const client = new TcbClient({
  credential: {
    secretId: process.env.TENCENTCLOUD_SECRETID,
    secretKey: process.env.TENCENTCLOUD_SECRETKEY,
  },
  profile: {
    httpProfile: {
      endpoint: "tcb.tencentcloudapi.com",
    },
  },
});

client
  .CreateEnv({
    PackageId: "baas_personal",
    Alias: "tenant-a-env",
    Resources: ["storage"],
    ExternalStorage: {
      Enabled: true,
      BucketName: "tcb-ext-stor-1257619089",
      Region: "ap-shanghai",
      BasePath: "ext-storage-v1",
    },
    Period: 1,
  })
  .then(
    (resp) => {
      console.log(resp.EnvId);
    },
    (err) => {
      console.error("error", err);
    },
  );

确认生效

环境创建完成后，调用 DescribeEnvs 查看 Storages[0]。共享桶环境没有自己的桶，Bucket 为空字符串，实际使用的桶名、地域和 BasePath 在 ExternalStorage 中：

{
  "Bucket": "",
  "Region": "ap-shanghai",
  "ExternalStorage": {
    "Enabled": true,
    "BucketName": "tcb-ext-stor-1257619089",
    "Region": "ap-shanghai",
    "BasePath": "ext-storage-v1"
  }
}

判断一个环境的云存储是否使用共享桶：Bucket 为空，且 ExternalStorage.Enabled 为 true。不要只看 Bucket 是否有值——共享桶环境下它恰好是空的。

静态托管使用共享桶

CreateEnv 中的 ExternalStorage 只作用于云存储，不会开通静态网站托管。静态托管使用的存储桶在开通托管时确定，开通后无法更换，由平台分配：平台版环境在创建时会自动开通静态托管，并分配平台的共享桶，各环境同样以 BasePath 隔离（默认取环境 ID）。

• 云存储和静态托管使用的桶相互独立，可能是同一个桶，也可能是不同的桶
• 控制台与 CLI 均未提供指定托管存储桶的入口
• 可通过 DescribeEnvs 返回的 StaticStorages[0] 查看托管实际使用的桶：共享桶下 Bucket 为空，桶名与 BasePath 在 ExternalStorage 中

文件路径

共享桶环境中，文件在 COS 桶里的实际 Key 是 BasePath/文件路径，但通过云开发访问文件时，使用的始终是不带 BasePath 的路径，由后台自动拼接：

场景	路径写法
云开发 SDK、CLI、MCP 上传或管理文件，fileID 中的文件路径	不带 BasePath，例如 images/logo.png
通过静态托管域名或云存储 CDN 域名访问文件	不带 BasePath，例如 https://<托管域名>/index.html（托管域名下拼上 BasePath 会返回 404）
直接调用 COS 接口读写桶	需要自行拼接，例如 ext-storage-v1/images/logo.png

直接调用 COS 接口时，账号级密钥可以访问整个桶，环境之间的目录隔离需要由调用方保证，务必只读写本环境 BasePath 下的对象。