如何配置访问OSS文件时的预览行为？

场景一：因OSS安全策略导致强制下载

此场景的特征是响应头中包含 x-oss-force-download: true。

• 原因：为防止特定类型文件（如HTML）在浏览器中被直接执行而引发潜在安全风险，当您使用OSS默认域名或传输加速域名访问特定时间点之后创建的Bucket时，OSS会针对部分地域、部分文件类型强制添加 x-oss-force-download: true 和 Content-Disposition: attachment 响应头，使浏览器强制下载文件。

  详细策略请参见本文末尾的附录：OSS域名强制下载规则速查表。

• 解决方案：使用自定义域名访问OSS资源

• 操作步骤：

  1. 绑定自定义域名到Bucket：登录OSS控制台，在目标Bucket的域名管理页面，将您已完成ICP备案的自定义域名绑定到该Bucket。

  2. 配置CNAME解析：前往您的域名解析服务商（如阿里云DNS），为您的自定义域名添加一条CNAME记录，指向OSS提供的CName地址。

  3. 使用新域名访问：完成配置后，使用您的自定义域名URL访问文件，即可实现在线预览。

场景二：因文件元数据（Metadata）设置导致强制下载

此场景的特征是响应头中包含 Content-Disposition: attachment，但没有 x-oss-force-download 字段。

• 原因：文件的元数据中 Content-Disposition 字段被显式设置为 attachment。这个设置会指示浏览器将文件作为附件下载，而不是内联（inline）展示。此设置通常用于生成临时下载链接，如果设置后未被及时清除，会导致该文件后续所有访问都变成下载行为。

• 解决方案：修改文件的Content-Disposition元数据为 inline

  • 通过控制台修改

    1. 登录OSS管理控制台，进入目标Bucket的文件管理 > 文件列表页面。

    2. 找到目标文件，在其右侧操作列，选择┇ > 设置文件元数据。

    3. 在弹出的对话框中，找到Content-Disposition字段，将其值修改为inline。

    4. 单击确定保存设置。

  • 通过ossutil工具批量修改

    # 将指定文件的Content-Disposition设置为inline
    ossutil set-meta oss://your-bucket/your-object.pdf Content-Disposition:inline

场景三：因Content-Type不正确导致浏览器无法预览

此场景的特征是响应头正常，但浏览器仍然选择下载。

• 原因 文件的Content-Type（也称为MIME类型）元数据设置错误或缺失。例如，将一个JPG图片文件的Content-Type 错误地设置为application/octet-stream，浏览器会因无法识别其真实类型而选择下载。

• 解决方案：为文件设置正确的Content-Type

  • 通过控制台修改

    1. 登录OSS管理控制台，进入目标Bucket的文件管理 > 文件列表页面。

    2. 找到目标文件，在其右侧操作列，选择┇ > 设置文件元数据。

    3. 在弹出的对话框中，找到Content-Type字段，将其修改为正确的值。

    4. 单击确定保存设置。

    常见文件类型的正确Content-Type示例：

    • 图片：image/jpeg, image/png, image/gif, image/webp

    • 视频：video/mp4

    • PDF文档：application/pdf

    • HTML文件：text/html

    • 纯文本：text/plain

  • 通过ossutil工具批量修改

    # 将指定文件的Content-Type设置为image/jpeg
    ossutil set-meta oss://your-bucket/your-object.jpg Content-Type:image/jpeg

修改元数据后未生效：检查CDN缓存

如果您在OSS之上使用了内容分发网络CDN进行加速，当您修改了OSS文件的元数据（如 Content-Type 或 Content-Disposition）后，可能因为CDN节点仍缓存着旧的配置而无法立即生效。

解决方案：登录CDN控制台，对修改过的文件URL执行刷新操作，以清除CDN上的缓存。具体操作，请参见刷新和预热资源。

如何强制文件被下载而非预览？

与实现在线预览相反，如果您希望用户访问文件时总是触发下载，可以通过以下方式实现。

• 方法一（推荐）：在OSS侧设置。按照场景二中的方法，将文件的 Content-Disposition 元数据设置为 attachment 即可。此方法适用于对单个文件进行永久性设置。

• 方法二：在CDN侧配置。如果您使用了CDN，可以在CDN控制台通过配置缓存配置的出站响应头，添加Content-Disposition: attachment。此方法无需修改OSS源站文件，适合对特定路径或文件类型进行批量、灵活的规则配置。

浏览器本身不支持预览该文件格式

某些专业格式的文件（如 .psd、.ai、.sketch 等）本身不被主流浏览器支持在线预览。在这种情况下，即使OSS和CDN配置完全正确，浏览器也只会执行下载操作。

解决方案：为您的浏览器安装支持该文件格式的预览插件。或者，您也可以考虑使用专业的文档预览服务，如WebOffice在线预览。