Astro + Cloudflare Pages：从本地构建到全球边缘

静态网站的部署看起来只是“上传一个文件夹”，但真正决定它是否可靠的，是构建目录、资源路径、缓存和域名这几层能否对齐。

构建阶段发生了什么

Astro 会把 Markdown、组件和样式编译成浏览器可以直接读取的 HTML、CSS 与 JavaScript。默认输出目录是 dist：

npm run build

# 输出结构
dist/
├── index.html
├── _astro/
├── images/
└── posts/

部署时必须上传 dist 里面的全部内容和目录结构。如果压缩工具把路径分隔符处理错了，首页可能正常，但 CSS、图片和文章子页面都会返回 404。

Pages 与自定义域名

Cloudflare Pages 为每次部署生成不可变版本，再把生产版本绑定到 pages.dev 地址。自定义域名只是指向这个生产版本，并不复制一份网站。

这意味着排查问题时可以先比较两个地址：

1. 项目名.pages.dev 也有问题，通常是构建或上传错误；
2. 只有自定义域名有问题，才继续检查 DNS、证书与重定向。

缓存边界

带内容哈希的文件，例如 BaseLayout.DrLqh44T.css，可以长期缓存；HTML 则应该快速重新验证。Astro 默认的文件命名已经为这种策略做好了准备。

部署并不是流程的最后一步。对首页、资源文件、文章页分别做一次 HTTP 检查，才算完成交付。