Astro博客上线：Cloudflare Pages入门

从静态博客、GitHub 仓库到 Cloudflare Pages 自动部署，说明构建设置、域名、成功检查与失败排查。

2026/07/07 · 4 分钟 · 自建与维护 · 更新于 2026/10/01

入门教程自建与维护

把教程写在自己的站点上，最大的好处是可以持续修订。链接留在原处，文章会慢慢变得更有用。

这里先搭一条简单的发布路径：**Astro 静态博客 → GitHub → Cloudflare Pages。**邮箱、图床和其他工具可以以后再补。

预计 30—60 分钟，不含内容准备。依据 Astro 与 Cloudflare 官方文档整理。部署成功还要以你的构建日志和线上页面为准。

先分清静态与动态

博客文章适合在构建时生成 HTML。访问时直接读取页面，不需要每次运行完整博客程序。

登录、修改文章等能力需要服务端接口。它们可以独立承载，不必让整个博客都按动态方式运行。选择哪种方式，要看项目功能与框架配置。

准备一个 Astro 项目

可以从自己的现有项目开始，也可以用 Astro 创建新项目：

npm create astro@latest

跟随创建向导进入新目录，然后启动本地预览。先确认页面能打开，文章图片路径正确，再提交到 GitHub。

对于静态博客，配置中的输出方式应与静态生成一致：

import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://你的域名",
  output: "static",
});

上面的配置只是最小示例。不要直接覆盖已有项目的插件与其他设置。

在 Pages 连接仓库

在 Cloudflare Pages 中创建项目，连接包含博客的 GitHub 仓库。核对：

如果项目使用 pnpm，保留对应锁文件，并使本地与构建环境的包管理器版本一致。具体设置以 Cloudflare Astro 部署指南 为准。

绑定域名后检查什么

先确认默认 Pages 地址能正常访问，再添加自定义域名，并按面板提示处理 DNS。

部署完成后，至少检查：

• 首页和一篇文章都能打开
• 图片、样式和下载资源没有 404
• RSS 与站点地图可访问
• canonical 指向正式域名
• 草稿没有生成公开页面
• 线上版本对应刚提交的版本

看到代码推送成功，只说明 GitHub 收到了提交；只有部署日志成功、线上内容正确，才算发布完成。

构建失败怎样排查

先读最新日志的明确错误，不要反复点击重试。

缺少依赖就检查安装与锁文件；类型错误就检查源码；图片不存在就修引用或补文件。如果项目生成了很大的服务端包，应先判断哪些页面真正需要动态运行。

小酒馆此前的部署日志出现过服务端包超过该次限制的问题。对应的修复方向，是把博客页面与管理接口分开，让文章恢复静态生成。平台限制以当前官方文档为准。

为以后维护留一条路

保留可回退的版本，每次发布执行同一组检查。修改内容时更新修订日期，并记录变动。第一次上线之后，先把文章写好，再考虑更多服务。

继续阅读：第一次 API 调用、ComfyUI 第一张图。

官方参考：Astro 文档、Cloudflare Pages、Pages Astro 部署指南。