Astro 静态博客部署笔记

这篇主要整理 Astro 静态站从源码到正式域名的部署链路。源码放在 GitHub，Cloudflare Pages 负责构建和发布，域名继续在阿里云注册，DNS、CDN 与 HTTPS 则交给 Cloudflare。

文中的仓库和域名都是示例值，方便以后按同一思路重新配置。

整体链路

本地 Astro 项目
  ↓ git push
GitHub 仓库
  ↓ 自动构建
Cloudflare Pages
  ↓ 自定义域名、CDN、HTTPS
example.com

几个平台的职责可以先分清：

阿里云：域名注册与续费
GitHub：源码托管与版本管理
Cloudflare Pages：构建与静态发布
Cloudflare DNS：解析、CDN、HTTPS 与重定向

域名接入 Cloudflare 后，注册商仍然是阿里云，只是权威 DNS 换成了 Cloudflare。

示例参数

笔记统一使用以下占位值：

GitHub 仓库：your-account/astro-blog
生产分支：main
Pages 项目：astro-blog
默认域名：astro-blog.pages.dev
自定义域名：example.com

example.com 是文档保留域名，实际配置时要全部替换。

本地构建

部署前先保证本地生产构建正常：

corepack enable
pnpm install
pnpm build

Astro 默认输出到 dist。检查重点：

• 构建命令没有报错。
• dist/index.html 已生成。
• 图片、字体和脚本出现在构建结果中。
• 页面资源没有引用本机绝对路径。
• .gitignore 已排除 node_modules、.astro 和 dist。

如果在 astro.config.mjs 中修改了 outDir，Cloudflare Pages 的输出目录也必须跟着修改。

GitHub 仓库

首次推送大致如下：

git init
git branch -M main
git remote add origin https://github.com/your-account/astro-blog.git
git add package.json pnpm-lock.yaml astro.config.mjs src public
git commit -m "Initial Astro site"
git push -u origin main

已经连接远端时，用下面两条确认当前状态：

git status -sb
git remote -v

这里不使用 git add -A 作为固定写法。工作区混有其他改动时，明确列出需要提交的文件会更稳妥。

Cloudflare Pages 参数

Cloudflare 控制台中的入口：

Workers 和 Pages
→ 创建应用程序
→ Pages
→ 连接 Git
→ 选择 GitHub 仓库

Astro 静态站使用 Pages 的 Git 构建，不需要进入 Worker 的 Wrangler 部署流程。

常用构建参数：

项目名称：astro-blog
生产分支：main
框架预设：Astro
构建命令：pnpm build
构建输出目录：dist
根目录：/

如果项目放在 Monorepo 的 apps/blog 中，根目录填写 apps/blog。构建命令和输出目录都以这个根目录为基准。

部署成功后会得到类似下面的地址：

https://astro-blog.pages.dev

先确认默认域名可以正常访问，再继续绑定自己的域名。这样能够把“构建问题”和“DNS 问题”分开排查。

运行时版本

本地和 Cloudflare 使用不同版本的 Node.js 或 pnpm，容易出现只有线上失败的情况。

可以在 package.json 中固定包管理器版本：

{
  "packageManager": "pnpm@11.5.2"
}

Node.js 主版本可以记录在 .nvmrc：

22

版本调整后，需要在 Pages 构建日志中确认实际生效的 Node.js、pnpm 和 Astro 版本。

构建失败记录

遇到失败时，先找日志中第一条真正的错误，后面的内容往往只是连带结果。

常见原因：

• Pages 构建命令与本地不一致。
• 输出目录填写错误。
• pnpm-lock.yaml 没有提交。
• 环境变量只存在于本地。
• 文件名大小写不一致。
• Markdown 引用了不存在的资源。
• 静态资源路径写成了本机路径。

修改后重新验证：

pnpm build
git status -sb
git add package.json pnpm-lock.yaml astro.config.mjs src public
git commit -m "Fix production build"
git push origin main

新的提交会触发新的 Pages 部署，失败的部署不会替换最后一个成功版本。

单文件过大

图片较多时，构建产物可能出现单文件过大的问题。一般是原图未经压缩，或者响应式图片生成了没有必要的超大尺寸。

本地构建后可以按文件大小排序：

pnpm build
Get-ChildItem -Path dist -Recurse -File |
  Sort-Object Length -Descending |
  Select-Object -First 20 FullName, Length

处理思路：

• 压缩原始图片。
• 转换为 WebP 或 AVIF。
• 限制响应式图片宽度。
• 不把大文件直接复制进 public。
• 确实需要的大文件改用对象存储。

图片宽度不必覆盖原始照片的最大分辨率。博客正文和画廊通常准备几档实际会用到的宽度即可。

域名接入 Cloudflare

Pages 默认域名正常后，再到 Cloudflare 添加站点：

添加站点
→ 输入 example.com
→ 选择 Free 计划
→ 扫描现有 DNS 记录

自动扫描结果需要与阿里云 DNS 中的原记录逐项比较。重点保留：

• 域名所有权验证记录。
• 仍在使用的子域名。
• 指向其他服务的 CNAME。

不要在还没核对记录时直接切换 Nameserver，否则可能导致已有服务暂时中断。

DNS 橙云与灰云

Cloudflare 中：

橙云：经过 Cloudflare 代理
灰云：仅提供 DNS 解析

网站的 A、AAAA 和 CNAME 通常可以开启橙云。SSH、SFTP 等非 HTTP 服务一般保持灰云，只让 Cloudflare 返回真实解析结果。非 Web 服务误开橙云后，对应客户端可能无法连接。

修改 Nameserver

Cloudflare 会为每个站点分配两条 Nameserver。这里只能使用控制台给当前域名分配的值，不能复制其他人的记录。

阿里云控制台中的位置：

域名
→ 域名列表
→ 选择目标域名
→ 管理
→ DNS 服务器
→ 修改 DNS 服务器

把原来的阿里云 Nameserver 替换成 Cloudflare 提供的两条，保存后回到 Cloudflare 发起检查。

公开 DNS 可以这样查询：

nslookup -type=ns example.com 1.1.1.1

返回结果与 Cloudflare 分配的 Nameserver 一致，说明委派已经生效。DNS 缓存刷新可能需要几分钟到数小时。

Pages 自定义域名

域名状态变为活动后，回到 Pages 项目：

Workers 和 Pages
→ astro-blog
→ 自定义域
→ 设置自定义域

一般会同时添加：

example.com
www.example.com

Cloudflare 会创建或提示创建对应 DNS 记录，并自动签发 HTTPS 证书。

如果长时间停留在验证状态，检查：

• Nameserver 是否已经生效。
• 是否存在冲突的同名记录。
• CAA 是否限制证书签发。
• 域名是否绑定在另一个 Pages 项目上。

www 重定向

根域名与 www 同时提供相同内容时，选一个作为主地址，另一个做永久重定向。

例如把：

https://www.example.com/*

重定向到：

https://example.com/${1}

规则使用 301，并保留查询字符串。发布后要测试首页、文章路径和带查询参数的地址。

如果选择 www 作为主域名，就把方向反过来，同时修改 Astro 的 site、Canonical URL 和 Sitemap 地址。

HTTPS 检查

自定义域名绑定后记录几个检查点：

• Pages 自定义域状态为活动。
• HTTPS 证书已经签发。
• “始终使用 HTTPS”已经开启。
• 页面没有循环重定向。
• 图片、字体和脚本没有使用 http://。

证书还在签发时，HTTPS 暂时不可用不一定表示配置错误，可以等状态稳定后再继续判断。

日常更新

后续更新基本只剩本地验证、提交和推送：

pnpm build
git status -sb
git add src public
git commit -m "Update site content"
git push origin main

如果修改了配置、依赖或文档，按实际范围把对应文件加入暂存区。推送到生产分支后，Cloudflare Pages 会自动开始下一次构建。

需要回退时，可以重新部署 Pages 中已成功的历史版本，也可以通过 Git 提交修复后再次推送。

排查顺序

为了少绕弯，可以按下面的顺序判断：

1. 本地 pnpm build 是否成功。
2. GitHub 是否已经收到最新提交。
3. Pages 构建是否成功。
4. pages.dev 默认域名是否可访问。
5. Nameserver 是否已经生效。
6. 自定义域名是否处于活动状态。
7. DNS 记录和代理状态是否正确。
8. HTTPS、重定向和 Canonical URL 是否一致。

先确认默认域名，再检查自定义域名；先确认 DNS，再检查证书和跳转。把每一层单独验证，问题通常会清楚很多。

最后检查

• Pages 默认域名能够访问。
• 根域名和 www 均已绑定。
• 非主域名会 301 跳转到主域名。
• 首页、文章、静态资源、RSS 和 Sitemap 正常。
• Canonical URL 使用最终主域名。
• 非 Web 服务保持“仅 DNS”。
• GitHub 推送可以触发 Pages 自动构建。
• 构建失败时，上一成功版本仍然在线。

这套方案配置完成后，日常维护其实很简单。大部分时间只需要关心本地构建和 Git 提交；域名、证书与 CDN 都由 Cloudflare 持续处理。