Deploy an Astro static site to Alibaba Cloud OSS and ESA

Astro can produce a complete static website at build time. When a site does not need server-side rendering, the generated files can be stored directly in Alibaba Cloud OSS and delivered through Edge Security Acceleration (ESA).

This removes the web server from the request path. OSS stores the source files, ESA serves cached copies near visitors, and GitHub Actions handles repeatable deployment.

When this architecture fits

Use this architecture when the website is primarily made of:

• product pages;
• documentation and tutorials;
• Markdown content;
• static images, fonts, videos, and downloads;
• client-side interactions that do not require a server for the initial response.

It is not the right default for authenticated dashboards, frequently changing personalized content, or application APIs. Those features should use a separate backend rather than turning the entire content site into a dynamic server application.

Request path

The production request path is:

Visitor
  -> ESA edge node
  -> OSS origin, only when the edge cache misses

For a cache hit, OSS is not contacted. File size still matters, but DNS resolution, connection setup, TLS, routing quality, and edge-cache state often dominate the first request.

Configure Astro for static output

Set the canonical site URL in astro.config.mjs. Astro uses this value when generating canonical URLs and sitemaps.

import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://example.com",
  integrations: [sitemap()],
});

Run the production build:

pnpm build

The deployable website is written to dist/. Upload the contents of that directory to the root of the OSS bucket, not the directory itself.

Separate HTML from immutable assets

Astro gives generated assets content-based filenames such as:

/_astro/BaseLayout.G4i_dsa2.css

When the file changes, its name changes. This makes /_astro/ safe to cache in both browsers and ESA for one year.

HTML uses stable URLs such as /library/ and /apps/apple/. Cache HTML at the edge, but do not keep it in the browser for a long time. A practical baseline is:

Resource	Browser cache	ESA edge cache
/_astro/*	1 year	1 year
HTML routes ending in /	no cache	7 days
images, fonts, and video	30 days	1 year
sitemap, robots, and verification files	default	1 month

Long edge caching is safe only when deployment also purges changed HTML URLs.

Deploy with short-lived credentials

GitHub Actions should authenticate to Alibaba Cloud through OIDC and assume a narrowly scoped RAM role. Avoid storing permanent access keys in repository secrets.

The deployment pipeline should:

1. install dependencies with a frozen lockfile;
2. run Astro checks and build the site;
3. obtain temporary Alibaba Cloud credentials through OIDC;
4. synchronize dist/ to the OSS bucket;
5. delete files that no longer exist locally;
6. purge changed HTML and metadata URLs from ESA.

Hashed files under /_astro/ do not need purging because each changed file receives a new URL.

Preserve clean URLs

Generate routes with a trailing slash:

/library/deploy-astro-to-alibaba-cloud-oss-esa/

Store the page as:

library/deploy-astro-to-alibaba-cloud-oss-esa/index.html

Configure ESA to rewrite directory requests to index.html when required. Redirect non-file URLs without a trailing slash to the canonical trailing-slash URL. Exclude real file extensions from that redirect.

Verify the deployment

Do not judge performance from file size alone. Inspect the request timing and response headers:

curl -I https://example.com/

Useful headers include:

x-site-cache-status: HIT
age: 120
cache-control: no-cache

For hashed assets, expect a long browser lifetime:

cache-control: max-age=31536000

A small file can still be slow when the browser is waiting for DNS, TCP, TLS, a proxy, an uncached edge node, or a poor network route. Separate connection time, time to first byte, and download time before changing the application.

SEO checks after deployment

Confirm that every public page has:

• a unique title and meta description;
• one canonical URL;
• valid language alternates only when translations exist;
• crawlable HTML content without requiring JavaScript;
• internal links from the Library index and related content;
• inclusion in the XML sitemap.

Submit the sitemap to Google Search Console, Bing Webmaster Tools, and the relevant regional search platforms. Deployment makes pages available; indexing and ranking still depend on useful content, clear site structure, and continued maintenance.

References

• Astro deployment guide
• Astro sitemap integration
• Alibaba Cloud ESA documentation