Object Storage Service:How to configure browser preview behavior for OSS objects?

Scenario 1: Forced download due to an OSS security policy

This scenario occurs when the response header contains x-oss-force-download: true.

• Cause: To prevent security risks that arise when certain file types, such as HTML, are executed directly in a browser, OSS enforces a security policy. When you use an OSS default domain name or an acceleration endpoint to access objects in buckets created after a specific time, OSS adds the x-oss-force-download: true and Content-Disposition: attachment headers to the response. This forces the browser to download the object.

  For more information about the policies, see Appendix: Quick reference for OSS forced download rules at the end of this topic.

• Solution: Use a custom domain name to access OSS resources.

• Procedure:

  1. Map a custom domain name to the bucket: Log on to the OSS console. On the Domain Names page of the target bucket, map your custom domain name that has an ICP filing to the bucket.

  2. Configure a CNAME record: Go to your domain name provider, such as Alibaba Cloud DNS. Add a CNAME record that points your custom domain name to the CNAME address provided by OSS.

  3. Access the object using the new domain name: After the configuration is complete, use the URL of your custom domain name to access the object. The object can then be previewed online.

Scenario 2: Forced download due to object metadata settings

This scenario occurs when the response header contains Content-Disposition: attachment but not x-oss-force-download.

• Cause: The Content-Disposition field in the object's metadata is explicitly set to attachment. This setting instructs the browser to download the object as an attachment instead of displaying it inline. This setting is often used to generate temporary download links. If the setting is not cleared, all subsequent requests for the object trigger a download.

• Solution: Change the object's Content-Disposition metadata to inline.

  • Modify in the console

    1. Log on to the OSS console. In the navigation pane on the left, go to the Files > Objects page of the target bucket.

    2. Find the target object. In the Actions column, choose ... > Set Object Metadata.

    3. In the dialog box that appears, find the Content-Disposition field and change its value to inline.

    4. Click OK to save the settings.

  • Modify in batches using ossutil

    # Set the Content-Disposition of the specified object to inline.
    ossutil set-props oss://your-bucket/your-object.pdf --content-disposition inline --metadata-directive update

Scenario 3: Browser fails to preview the object due to an incorrect Content-Type

This scenario occurs when the response header is normal, but the browser still downloads the object.

• Cause: The Content-Type (also known as Multipurpose Internet Mail Extensions (MIME) type) metadata of the object is missing or incorrect. For example, if the Content-Type of a JPG image is incorrectly set to application/octet-stream, the browser downloads the object because it cannot identify the actual file type.

• Solution: Set the correct Content-Type for the object.

  • Modify in the console

    1. Log on to the OSS console. In the navigation pane on the left, go to the Files > Objects page of the target bucket.

    2. Find the target object. In the Actions column, choose ... > Set Object Metadata.

    3. In the dialog box that appears, find the Content-Type field and change it to the correct value.

    4. Click OK to save the settings.

    Examples of correct Content-Type for common file types:

    • Images: image/jpeg, image/png, image/gif, image/webp

    • Videos: video/mp4

    • PDF documents: application/pdf

    • HTML files: text/html

    • Plain text: text/plain

  • Modify in batches using ossutil

    # Set the Content-Type of the specified object to image/jpeg.
    ossutil set-props oss://your-bucket/your-object.jpg --content-type image/jpeg --metadata-directive update

Changes to metadata do not take effect: Check the CDN cache

If you use Alibaba Cloud Content Delivery Network (CDN) to accelerate access to OSS, changes to object metadata, such as Content-Type or Content-Disposition, may not take effect immediately. This is because CDN points of presence (POPs) might still serve the cached version with the old configuration.

Solution: Log on to the CDN console and purge the cache for the modified object's URL. For more information, see Refresh and prefetch resources.

How to force an object to download instead of being previewed

If you want to always force a download when a user accesses an object, you can use one of the following methods.

• Method 1 (Recommended): Configure in OSS. As described in Scenario 2, set the object's Content-Disposition metadata to attachment. This method is ideal for applying a permanent setting to a single object.

• Method 2: Configure in CDN. If you use CDN, you can add the Content-Disposition: attachment header in the CDN console. You can configure this as an outbound response header in the Cache Settings. This method does not require changes to the source object in OSS and is useful for flexible, batch configurations based on specific paths or file types.

The browser does not support the file format for preview

Mainstream browsers do not support online previews for some professional file formats, such as .psd, .ai, or .sketch. In this case, the browser downloads the file even if the OSS and CDN configurations are correct.

Solution: You can install a browser plugin that supports previewing the file format. You can also use a professional document preview service, such as WebOffice Online Preview.

OSS default domain names

Acceleration endpoint