教程

将 Astro 静态网站部署到阿里云 OSS 和 ESA

使用 OSS、ESA 边缘缓存和 GitHub Actions 部署 Astro 静态网站，不再让低带宽云服务器进入访问链路.

发布于 更新于 Astro · 阿里云 · 部署

Astro 可以在构建阶段生成一套完整的静态网站. 当网站不依赖服务端渲染时，可以直接把生成文件存入阿里云 OSS，再通过边缘安全加速 ESA 向不同地区的访客分发.

这套架构不需要让 Web 服务器参与页面请求. OSS 负责保存源文件，ESA 负责就近缓存和响应，GitHub Actions 负责可重复的自动部署.

哪些网站适合

alt text 这套架构适合以以下内容为主的网站：

  • 产品介绍页；
  • 软件说明和教程；
  • Markdown 内容；
  • 静态图片、字体、视频和下载文件；
  • 不依赖服务端生成首屏的客户端交互.

登录后台、高频变化的个性化页面和业务 API 不适合直接套用这套方案. 这些能力应该使用独立后端，而不是把整个内容站改成动态服务器应用.

实际访问链路

生产环境中的请求链路是：

访客
  -> ESA 边缘节点
  -> OSS 源站，仅在边缘缓存未命中时访问

缓存命中时，ESA 不会访问 OSS. 文件体积仍然重要，但首次请求往往更容易受到 DNS、连接建立、TLS、网络路由和节点缓存状态影响.

配置 Astro 静态构建

在 astro.config.mjs 中配置正式域名. Astro 会使用它生成 canonical 和 sitemap.

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

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

执行正式构建：

pnpm build

可部署文件会生成到 dist/. 上传时应把 dist/ 内部的内容同步到 OSS Bucket 根目录，而不是把 dist 文件夹本身上传上去.

分开处理 HTML 和不可变资源

Astro 会为生成资源使用基于内容的文件名，例如：

/_astro/BaseLayout.G4i_dsa2.css

文件内容改变后，文件名也会改变. 因此 /_astro/ 可以放心地在浏览器和 ESA 中缓存一年.

HTML 使用 /library/、/apps/apple/ 这样的稳定地址. HTML 可以在边缘节点长期缓存，但不应该在浏览器中长期保存. 一套实用的起始规则是：

资源浏览器缓存ESA 边缘缓存
/_astro/*1年1年
以 / 结尾的 HTML 路由不缓存7天
图片、字体和视频30天1年
sitemap、robots 和验证文件默认1个月

只有在部署流程会同步刷新已修改 HTML 的前提下，HTML 的长期边缘缓存才是安全的.

使用短期凭据自动部署

GitHub Actions 应通过 OIDC 获取临时身份并扮演最小权限的 RAM 角色. 不要把长期 AccessKey 保存到仓库 Secret 中.

部署流水线应该依次完成：

  1. 使用锁定文件安装依赖；
  2. 执行 Astro 检查并构建；
  3. 通过 OIDC 获取阿里云临时凭据；
  4. 把 dist/ 同步到 OSS Bucket；
  5. 删除线上已经不存在的旧文件；
  6. 刷新 ESA 中发生变化的 HTML 和站点元数据.

/_astro/ 下的哈希资源不需要刷新缓存，因为文件变化时会得到一个新 URL.

保持干净且唯一的 URL

文章路由统一使用结尾斜杠：

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

OSS 中对应的文件是：

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

必要时，通过 ESA 把目录请求重写到 index.html. 对没有文件扩展名且缺少结尾斜杠的地址执行 301 跳转，同时排除真实的静态文件.

验证部署结果

不能只根据文件体积判断性能. 应同时检查请求阶段和响应头：

curl -I https://example.com/

HTML 边缘缓存命中时，可能看到：

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

哈希静态资源应具备长期浏览器缓存：

cache-control: max-age=31536000

即使文件只有几 KB，DNS、TCP、TLS、代理、冷缓存节点或较差的网络路由仍然可能让请求变慢. 在修改应用代码前，应先分清连接时间、首字节时间和实际下载时间.

部署后的 SEO 检查

确认每个公开页面都具备：

  • 独立且准确的 title 和 meta description；
  • 唯一 canonical；
  • 只指向真实翻译页面的语言替代链接；
  • 不依赖 JavaScript 才能出现的正文；
  • 来自 Library 首页和相关文章的内部链接；
  • sitemap 中的正式 URL.

最后将 sitemap 提交给 Google Search Console、Bing Webmaster Tools 和需要覆盖的地区搜索平台. 部署只能保证页面可访问，最终收录和排名仍然取决于内容价值、站点结构和持续维护.

参考资料