绑定自定义域名访问OSS Bucket实现文件在线预览-对象存储(OSS)-阿里云帮助中心

OSS允许将自有域名绑定至Bucket、接入点或对象FC接入点，替代默认域名访问OSS资源。绑定后，可以使用自定义域名实现文件在线预览、提升品牌一致性，并灵活配置HTTPS证书和CDN加速等能力。

工作原理

自定义域名绑定至OSS的实现基于DNS的CNAME（Canonical Name）记录。通过将自定义域名指向OSS提供的默认域名，当用户访问自定义域名时，DNS系统将其解析到对应的OSS访问域名，从而实现对OSS资源的访问。

配置过程分为三步：绑定域名、配置CNAME解析、验证访问。OSS支持将自定义域名绑定至以下4种访问域名，请根据业务需求选择：

场景	绑定方式	说明
托管静态资源、文件在线预览	绑定至外网访问域名	最常用的方式，满足基础文件访问需求
跨国或远距离加速传输	绑定至传输加速域名	需先开启传输加速功能
多应用或多团队差异化权限访问	绑定至接入点域名	需先创建接入点
数据触发函数计算处理	绑定至对象FC接入点域名	需先创建对象FC接入点

开启自定义域名访问

重要

请确保已拥有一个已注册的域名或注册一个新域名。若Bucket位于中国内地，绑定的域名必须完成ICP备案。若Bucket位于非中国内地节点（如中国香港、新加坡等），绑定的自定义域名无需ICP备案。中国大陆用户访问境外节点时跨境网络延迟可能增大，请根据用户所在地域选择Bucket节点。

步骤一：绑定自定义域名

前往Bucket列表，单击目标Bucket名称，然后在左侧菜单栏单击Bucket 配置 > 域名管理，单击绑定域名。
说明
- 如需绑定至接入点域名，请前往接入点列表，单击目标接入点名称，然后单击接入点域名管理 > 绑定域名。
- 如需绑定至对象FC接入点域名，请前往对象FC接入点列表，单击目标对象FC接入点名称，然后在对象 FC 接入点域名管理区域单击绑定域名。
输入需要绑定的域名。系统将自动检测是否满足绑定条件，域名属于当前账户时可直接单击确认绑定完成绑定（绑定域名到接入点或对象FC接入点时不支持）。域名属于其他阿里云账户或其他域名服务商时，需要验证域名所有权，以阿里云购买的域名为例：
1. 使用域名归属的阿里云账号登录云解析DNS控制台，单击目标域名操作列的解析设置。
2. 单击添加记录，按照下方配置列表填写记录信息，其余配置项可保持默认设置。
  - 记录类型：选择TXT。
  - 主机记录：主机记录仅填写前缀部分，如_dnsauth。如果绑定的是子域名，还需要加上子域名前缀，如绑定image.example.com，则主机记录填写_dnsauth.image。
  - 记录值：填写OSS控制台显示的记录值。
3. 单击确定，如弹出解析变更确认窗口，再次单击确定。
4. 返回OSS控制台，单击验证域名所有权并绑定，将域名绑定至Bucket。

说明

域名解析记录添加后需要一段时间才能生效，如果页面报错，请等待几分钟后重试。TXT记录用于验证对域名的所有权，验证成功后即可删除，不影响后续使用。

步骤二：配置CNAME解析

将域名绑定后，自定义域名尚未生效，需要配置CNAME解析记录将自定义域名指向OSS访问域名。

重要

请务必先完成步骤一的域名绑定，再配置CNAME解析，否则通过自定义域名访问OSS时将无法正确识别Bucket，返回非预期内容。后续解除绑定关系后，也请及时删除CNAME记录。

域名属于当前阿里云账户时，可在控制台选择自动添加 CNAME 记录，系统会自动完成CNAME配置（绑定域名到接入点或对象FC接入点时不支持）。其他情况需手动配置，以阿里云购买的域名为例：

说明

如果提示存在相同的主机记录导致无法自动添加，请登录云解析DNS控制台确认该CNAME记录是否还在使用，不再使用可删除后重新添加。

使用域名归属的阿里云账号登录云解析DNS控制台，单击目标域名操作列的解析设置。

单击添加记录，按照下方配置列表填写记录信息，其余配置项可保持默认设置。

记录类型：选择CNAME。
主机记录：如果绑定的是主域名，填写@；如果绑定的是子域名，填写子域名前缀，如绑定image.example.com，则主机记录填写image。

在根域名（@）上配置 CNAME 记录不符合 DNS 协议规范：根域名必须包含 SOA 和 NS 记录，而 CNAME 记录与这些必需记录冲突（RFC 1034 §3.6.2），可能导致部分运营商的 DNS 服务器无法正确解析。建议使用 www 等子域名绑定 OSS，避免此协议兼容性问题。

说明
若已存在同名的A记录，需先删除A记录后再添加CNAME记录，两者不能共存于同一主机记录。如果A记录正在使用（如指向ECS或WAF），建议使用一个新的子域名绑定OSS，避免影响现有业务。

记录值：根据业务场景填写对应的目标域名。

场景	记录值
外网访问	CNAME域名（推荐，如`example-bucket.<region-id>.taihangcda.cn`）或外网访问域名
传输加速访问	传输加速域名，如`example-bucket.oss-accelerate.aliyuncs.com`
接入点访问	接入点域名，如`example-ap-1999************.oss-<region-id>.oss-accesspoint.aliyuncs.com`
对象FC接入点访问	对象FC接入点域名，如`example-fc-1999************.oss-<region-id>.oss-object-process.aliyuncs.com`

单击确定，如弹出解析变更确认窗口，再次单击确定。

说明

DNS解析的生效时间取决于记录的TTL（生存时间）设置，完全生效通常需要几分钟到几小时。配置后立即访问无效属于正常现象，请耐心等待或尝试清除本地DNS缓存。可通过dig example.com CNAME +short命令查看CNAME记录的指向和生效情况。

步骤三：验证自定义域名访问

完成域名绑定和CNAME配置后，通过以下方式验证自定义域名是否生效。

公共读和公共读写Bucket

在浏览器中直接通过URL访问。如 http://image.example.com/example.jpg 表示访问Bucket根目录的文件 example.jpg。

接入点和对象FC接入点不支持匿名访问，可通过ossutil生成预签名URL，然后在浏览器中访问。以接入点为例：

ossutil presign oss://example-ap-1999************-ossalias/example.jpg --addressing-style cname -e http://image.example.com

私有Bucket

访问私有读写权限的Bucket需要在文件URL中包含签名信息。以下操作演示如何通过控制台获取文件的签名URL，关于签名的详细信息和生成方式请参见签名版本4（推荐）。

前往Bucket列表，单击目标Bucket。
单击需要访问的目标文件右侧操作列的详情。
域名选择自定义域名，并选择绑定的自定义域名，然后单击复制文件 URL。
在浏览器中访问修改后的URL。

接入点和对象FC接入点不支持匿名访问，可通过ossutil生成预签名URL，然后在浏览器中访问。以接入点为例：

ossutil presign oss://example-ap-1999************-ossalias/example.jpg --addressing-style cname -e http://image.example.com

应用于生产环境

最佳实践

安全传输：启用HTTPS

为自定义域名配置SSL证书，强制使用HTTPS访问。HTTPS协议通过TLS/SSL加密传输数据，防止数据在传输过程中被窃取或篡改，避免浏览器显示不安全警告，提升用户信任度和品牌形象。
跨域访问：配置CORS规则

当前端应用（如部署在https://web.example.com）需要访问OSS资源（如https://oss.example.com）时，必须配置CORS跨域规则，允许来自应用域名的跨域请求，确保前端应用正常访问OSS资源。
平滑上线：零停机域名切换

当需要将Bucket域名切换到绑定的自定义域名时，采用以下分阶段切换策略可避免服务中断：
1. 准备阶段：完成域名绑定和CNAME配置，在测试环境中验证功能和性能。
2. 灰度发布阶段（建议在业务低峰期）：将部分业务流量切换至自定义域名，逐步放量。
3. 验证阶段：监控访问日志和错误率，确认服务正常。
4. 全量发布阶段：将全量流量切换至自定义域名，完成迁移。
5. 回滚预案：如遇问题，立即回滚至Bucket域名，分析问题根因后重新部署。
性能与安全：通过子域名隔离用途

根据不同业务用途分配不同子域名，如网页静态资源使用static.example.com，图片资源使用images.example.com。通过域名隔离实现浏览器并发连接数优化、独立缓存策略配置和精细化权限控制。
功能扩展：托管静态网站

如果目标是利用OSS托管完整的静态网站（包含HTML、CSS、JS等文件），在绑定自定义域名后，还需进一步配置静态网站托管功能，实现默认首页、404错误页面等网站基础功能。
性能说明：自定义域名的 DNS 解析耗时

自定义域名通过CNAME指向 OSS 域名，浏览器解析时先查询 CNAME 记录获取 OSS 域名，再查询该 OSS 域名的 A 记录获取 IP 地址。直接使用 OSS 默认域名（如bucket.oss-cn-hangzhou.aliyuncs.com）只需一次 DNS 查询，而自定义域名多一次 CNAME 查询，因此首次访问会略慢。这是 DNS 协议的正常解析机制，并非 OSS 服务异常。如需优化访问速度，可配置 CDN 加速或开启传输加速功能。
性能优化：配置CDN加速

对于需要向全球用户分发静态资源的场景，建议进一步配置CDN加速服务，通过全球分布的边缘节点缓存内容，获得更低的访问延迟和更优的用户体验。
业务连续：Bucket迁移后链接恢复

Bucket跨地域迁移后，默认域名（如oss-cn-hangzhou.aliyuncs.com）随目标地域变化而改变，基于旧域名的文件链接将全部失效。迁移前为Bucket绑定自定义域名，迁移完成后将域名重新绑定至新Bucket，或通过CDN加速域名更新源站地址为新Bucket，恢复链接访问。

风险防范

流量盗用防护：配置Referer防盗链

为防止图片、视频等资源被其他网站盗用，产生不必要的流量费用和带宽消耗，请配置Referer防盗链。通过白名单机制限制访问来源，有效控制成本并保护资源不被滥用。
行为审计与排障：启用访问日志

启用OSS实时日志查询，记录所有访问请求的详细信息，包括访问时间、来源IP、请求类型、响应状态等，便于安全审计、性能分析和异常排查。

配额与限制

绑定数量：每个Bucket最多可以绑定100个自定义域名。
域名唯一性：一个自定义域名在同一时间只能绑定到一个Bucket或接入点。如需改绑，必须先从原Bucket或接入点解绑，确保域名指向的唯一性和访问路径的明确性。

说明
对于部分使用旧版图片处理功能的用户，已用于图片处理的域名不能再绑定到Bucket。新版图片处理功能无此限制。
域名类型：不支持绑定中文域名和泛域名（如*.example.com），确保DNS解析的稳定性和兼容性。

说明
通过CDN加速OSS时，允许绑定泛域名，但该域名不会在OSS管理控制台显示。
顶级域名要求：绑定的自定义域名中涉及的顶级域名必须满足指定后缀的要求，否则会被视为无效域名导致绑定失败。更多信息，请参见顶级域名分类解析。

常见问题

如何控制通过自定义域名访问文件时的预览或下载行为？

文件的预览或下载行为由HTTP响应头Content-Disposition决定。使用OSS默认提供的域名访问时，OSS会为安全起见强制添加Content-Disposition: attachment下载头；而通过自定义域名访问时，OSS不会添加此头，从而使行为变得可控。

实现预览：使用自定义域名访问，并确保文件元数据中没有设置Content-Disposition: attachment以及文件的Content-Type（MIME类型）正确匹配文件格式。对于浏览器原生不支持预览的文件格式，可通过以下方式扩展预览能力：
- 对于.doc、.ppt、.pdf等办公文件，集成WebOffice在线预览服务实现文档预览。
- 对于.mov等特殊格式视频文件，使用视频转码服务转换为Web兼容格式后实现预览。
- 安装对应文件类型的浏览器预览插件。
强制下载：为文件的元数据手动设置Content-Disposition为attachment，浏览器将忽略预览尝试并直接下载文件。

说明
<video>或<audio>标签会优先播放媒体，可能会忽略attachment的下载建议。

绑定域名时校验失败，提示域名绑定在其他Bucket上怎么办？

遇到域名已被其他Bucket绑定的情况，可采用以下方案：

为当前业务使用一个新的子域名。如域名example.com已被其他Bucket绑定，可使用image.example.com等新的子域名进行绑定，通过域名层级实现业务隔离。
将域名从原有Bucket解绑，再绑定到目标Bucket。解绑操作步骤如下：
1. 如果已开启CDN加速，需要先修改CDN加速服务的源站信息，使加速域名不再指向OSS的Bucket域名，避免CDN回源失败。修改方式请参见配置源站。
2. 前往Bucket列表，单击原有绑定的Bucket名称，然后在左侧菜单栏单击Bucket 配置 > 域名管理。
3. 在域名列表中单击目标域名操作列的解绑，在弹出的对话框中单击确定，完成域名解绑。

通过API绑定域名时返回NeedVerifyDomainOwnership错误怎么办？

此错误表示未验证域名所有权。可通过以下方式解决：

调用CreateCnameToken接口创建域名所有权验证所需的CnameToken。

说明
CnameToken默认在创建完成后72小时内过期。如果在过期时间内重复创建，则返回已存在的CnameToken。
在域名服务提供商处配置TXT记录完成域名所有权验证。
调用PutCname接口绑定自定义域名。

CDN 已完成 TXT 域名验证后，OSS 绑定域名是否需要二次验证？

CDN 和 OSS 的域名归属验证相互独立，CDN 侧完成的 TXT 验证不会同步到 OSS。在 OSS 控制台绑定自定义域名时，需单独完成域名所有权验证（TXT 记录验证），具体操作请参见本文步骤一：绑定自定义域名中的 TXT 记录配置说明。

域名归属于当前阿里云账号时，可直接绑定，无需 TXT 验证。通过 API 绑定域名时，如果返回NeedVerifyDomainOwnership错误，表示域名所有权验证未完成，需完成 TXT 记录验证，具体请参见通过 API 绑定域名时返回 NeedVerifyDomainOwnership 错误怎么办？。

配置完成后访问自定义域名无效或仍访问到旧地址？

这很可能是由于本地及运营商DNS缓存导致的解析延迟。为提升解析效率，DNS系统各层级节点会依据TTL值将域名解析结果缓存一段时间。当CNAME记录变更后，若缓存尚未过期，访问请求仍可能被指向旧的地址。建议等待十分钟后再尝试，或手动清除本地DNS缓存：

Windows

ipconfig /flushdns

macOS

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Linux

sudo systemd-resolve --flush-caches

添加CNAME记录时提示与已有A记录冲突怎么办？

根据DNS协议规范，同一主机记录下CNAME记录不能与A记录共存。如果当前域名已有A记录指向其他服务（如ECS、WAF），有以下两种解决方案：

使用一个新的子域名绑定OSS。例如，主域名example.com已有A记录，可使用oss.example.com绑定OSS，两者互不干扰。
如果必须使用当前域名，需先删除A记录再添加CNAME记录。删除前请确认A记录已无业务依赖，否则可能导致原有服务中断。

为何"域名B CNAME到域名A，域名A再绑定OSS"的方式会访问失败？

因为OSS会严格校验HTTP请求头中的Host字段，要求其必须与Bucket中实际绑定的域名完全一致。当访问域名B时，Host头为“域名B”，与绑定域名不匹配导致校验失败。因此，必须将实际公网访问的域名直接绑定到Bucket，而不能通过域名间的CNAME转发实现。

绑定自定义域名后，之前的文件URL是否可以继续使用？

可以继续使用。绑定自定义域名不会影响OSS默认提供的域名访问，两者可以并存。获取之前的文件URL方法，请参见使用预签名URL下载或预览文件。

停止CNAME解析后，默认域名是否仍可访问？

可以。OSS默认域名（如your-bucket.oss-cn-hangzhou.aliyuncs.com）是Bucket创建时自动分配的访问地址，独立于自定义域名。停止自定义域名DNS解析（删除CNAME记录）后，自定义域名无法访问，但默认域名不受影响。Bucket权限为公共读或持有有效访问凭证时，默认域名可正常访问。

解绑自定义域名与停止DNS解析是两个独立操作：解绑需在OSS控制台域名管理页面操作，停止DNS解析需在DNS服务商处删除CNAME记录。仅停止DNS解析不会在OSS侧自动解绑。

自定义域名绑定OSS后只能用外网访问域名吗？可以绑定内网域名吗？

自定义域名绑定OSS后，只能用于公网（外网）访问，不能用于内网访问。

OSS的自定义域名功能是通过在DNS服务商处配置CNAME记录，将自有域名指向OSS Bucket的外网访问域名（如example-bucket.oss-<region-id>.aliyuncs.com）来实现的。该机制面向公网用户通过自有域名访问OSS资源。

而内网访问必须使用阿里云提供的内网Endpoint（如oss-<region-id>-internal.aliyuncs.com），且仅限于与OSS同地域的阿里云资源（如ECS、函数计算等）在VPC内通过私网调用。由于内网Endpoint不支持被外部DNS解析，也无法通过CNAME绑定到自定义域名，因此无法将自定义域名用于内网访问。

已经正常解析到WAF且有内容的域名可以绑定至Bucket吗？

可以绑定。WAF（Web应用防火墙）与OSS的CNAME解析在不同的网络层面工作，两者功能互不冲突。WAF主要负责应用层安全防护，而CNAME解析负责域名指向，可以同时配置。将WAF接入OSS的具体方法，请参见CDN回源OSS私有Bucket场景下串接WAF最佳实践。

使用自定义域名，为什么HTTP请求不了资源文件，会强制跳转HTTPS？

这是因为在自定义域名上开启了强制HTTPS跳转功能，导致所有HTTP请求被自动重定向为HTTPS请求。

OSS本身不支持强制跳转，但通过CDN绑定自定义域名并配置了HTTPS证书后，可在CDN的HTTPS配置中开启强制跳转（HTTP → HTTPS），此时系统会返回301/302重定向响应，使浏览器将HTTP请求转为HTTPS。

如果希望允许HTTP访问资源文件，请进入CDN控制台，找到对应域名，将跳转类型改为默认（即同时支持HTTP和HTTPS）。具体操作，请参见配置协议重定向。

CDN 加速 OSS 时遇到 ERR_SSL_VERSION_OR_CIPHER_MISMATCH 错误怎么办？

CDN 加速域名配置了多个源站（IP 源站和 OSS 源站）时，CDN 随机回源。若回源到未配置 HTTPS 的 IP 源站，SSL 握手失败，浏览器显示 ERR_SSL_VERSION_OR_CIPHER_MISMATCH 错误。可通过以下步骤解决：

登录 CDN 控制台，在域名管理中检查加速域名的源站配置。如存在 IP 源站，删除 IP 源站，仅保留 OSS 源站。
在加速域名的 HTTPS 配置中开启 HTTPS，选择与加速域名匹配的有效 SSL 证书。

通过自定义域名可以上传文件吗？

不可以直接通过自定义域名 URL 上传文件。OSS 的自定义域名本质上是 OSS REST API 端点，直接通过浏览器 URL 发起 HTTP PUT 上传请求会因缺少认证签名而被拒绝（返回 403 AccessDenied）。自定义域名主要用于通过 HTTP GET 方式访问已上传的文件（如图片、网页等静态资源）。

如果需要上传文件到 OSS Bucket，请使用以下工具：

ossbrowser：图形化工具，适合非技术用户。
ossutil：命令行工具，适合运维人员。
OSS SDK：适合开发者集成到应用程序中。

在 ossbrowser 中配置 Endpoint 时，可填写 OSS 外网域名或自定义域名，并确保 AccessKey 已正确配置。