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 from certain file types (such as HTML) being executed directly in a browser, OSS enforces a security policy. This policy adds the x-oss-force-download: true and Content-Disposition: attachment headers to the response, forcing a download when you use an OSS default domain name or an acceleration endpoint to access objects in buckets created after a specific date.

  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: Log on to the OSS console. On the bucket's Domain Names page, map your custom domain name that has an ICP filing.

  2. Configure a CNAME record: At 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 with the new domain: 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. While this is useful for creating temporary download links, if the setting is not cleared, all subsequent requests for the object will trigger a download.

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

  • Modify via the console

    1. Log on to the OSS console and navigate to the Objects page in the Object Management section of the target bucket.

    2. Find the target object. Click the ┇ icon in the Actions column and select 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 a specific object to inline.
    ossutil set-meta oss://your-bucket/your-object.pdf Content-Disposition:inline

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 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 via the console

    1. Log on to the OSS console and navigate to the Objects page in the Object Management section of the target bucket.

    2. Find the target object. Click the ┇ icon in the Actions column and select 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 a specific object to image/jpeg.
    ossutil set-meta oss://your-bucket/your-object.jpg Content-Type:image/jpeg

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 file 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 file'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 a file, you can use one of the following methods.

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

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

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, and .sketch. In this case, the browser downloads the file even if the OSS and CDN configurations are correct.

Solution: You can install a browser extension 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 endpoints