Object Storage Service:How do I configure the preview behavior for objects in OSS?

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 can occur when files, such as HTML files, are executed directly in a browser, OSS forces a download. This behavior occurs when you use an OSS default domain name or an acceleration endpoint to access a bucket created after a specific date. For certain regions and file types, OSS adds the x-oss-force-download: true and Content-Disposition: attachment response headers.

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

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

• Procedure:

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

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

  3. Access the file with the new domain name: After the configuration is complete, use the URL of your custom domain name to access the file. This allows the file to be previewed online.

Scenario 2: Forced download due to file metadata settings

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

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

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

  • Modify in the console

    1. Log on to the OSS console. Go to the Object Management > 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 a specific file to inline
    ossutil set-meta oss://your-bucket/your-object.pdf Content-Disposition:inline

Scenario 3: Browser cannot preview the file due to an incorrect Content-Type

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

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

• Solution: Set the correct Content-Type for the file

  • Modify in the console

    1. Log on to the OSS console. Go to the Object Management > 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 a specific file 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 a file 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, 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 file in OSS and is useful for flexible, batch configurations based on specific paths or file types.

The browser does not support previewing the file format

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