跳转到内容
ShokaX Astro Blog Theme

部署到 Cloudflare Pages

Cloudflare Pages 是 Cloudflare 提供的静态站点托管服务，基于强大的全球 CDN 网络，提供快速、安全的部署体验。

前置要求

Section titled “前置要求”

在开始之前，请确保：

  • ✅ 已在 GitHub / GitLab 上创建仓库并推送代码
  • ✅ 拥有 Cloudflare 账号
  • ✅ 项目已正确配置 package.json 中的 build 脚本

快速部署

Section titled “快速部署”

步骤 1：创建项目

Section titled “步骤 1：创建项目”
  1. 登录 Cloudflare Dashboard
  2. 进入 Workers & Pages 页面
  3. 点击 “Create application” → “Pages” → “Connect to Git”

TODO: 添加 Cloudflare Pages 创建项目界面截图

步骤 2：连接 Git 仓库

Section titled “步骤 2：连接 Git 仓库”
  1. 选择你的 Git 提供商（GitHub 或 GitLab）
  2. 授权 Cloudflare Pages 访问你的仓库
  3. 在仓库列表中选择 ShokaX 项目
  4. 点击 “Begin setup”

TODO: 添加选择仓库界面截图

步骤 3：配置构建设置

Section titled “步骤 3：配置构建设置”

在 Set up builds and deployments 页面配置：

项目名称：

  • 输入项目名称（如 my-blog）
  • 这将成为你的默认域名：my-blog.pages.dev

构建配置：

配置项值说明
Production branchmain生产分支（根据你的仓库调整）
Framework presetAstro自动检测并选择
Build commandbun run build构建命令
Build output directorydist输出目录

TODO: 添加构建配置界面截图

步骤 4：配置环境变量（可选）

Section titled “步骤 4：配置环境变量（可选）”

在 Environment variables 部分，可以添加构建时需要的环境变量：

变量名值说明
NODE_VERSION20Node.js 版本（如果需要）
SITE_URLhttps://yourdomain.com站点 URL

TODO: 添加环境变量配置界面截图

步骤 5：部署

Section titled “步骤 5：部署”
  1. 检查配置无误后，点击 “Save and Deploy”
  2. Cloudflare Pages 自动开始构建和部署
  3. 等待 1-3 分钟，构建完成后会显示部署成功页面

TODO: 添加部署进度界面截图

🎉 恭喜！ 你的 ShokaX 站点已成功部署到 Cloudflare Pages！

访问 https://your-project.pages.dev 即可查看。

配置说明

Section titled “配置说明”

构建命令

Section titled “构建命令”

Cloudflare Pages 使用 package.json 中的 build 脚本：

package.json
{
  "scripts": {
    "build": "bun run build:site && bun run build:index"
  }
}

这个命令会：

  1. 构建 Astro 站点（build:site）
  2. 生成 Pagefind 搜索索引（build:index）

astro.config.mjs 配置

Section titled “astro.config.mjs 配置”

确保 astro.config.mjs 中的 site 字段配置正确：

astro.config.mjs
export default defineConfig({
  site: "https://your-project.pages.dev",  // 或你的自定义域名
  // ...其他配置
});

自动部署

Section titled “自动部署”

Cloudflare Pages 默认启用 持续部署（Continuous Deployment）：

  • ✅ 推送到生产分支 → 自动触发生产环境部署
  • ✅ 推送到其他分支 → 自动创建预览部署（Preview Deployment）
  • ✅ 创建 Pull Request → 自动为 PR 创建预览链接

工作流程：

Terminal window
# 本地修改内容
echo "新文章内容" > src/posts/new-post.md


# 提交并推送
git add .
git commit -m "添加新文章"
git push origin main


# Cloudflare Pages 自动触发部署（1-3 分钟后生效）

自定义域名

Section titled “自定义域名”

添加域名

Section titled “添加域名”
  1. 进入项目的 Custom domains 标签
  2. 点击 “Set up a custom domain”
  3. 输入你的域名（如 blog.example.com 或 example.com）
  4. 点击 “Continue”

TODO: 添加自定义域名设置界面截图

配置 DNS

Section titled “配置 DNS”

Cloudflare Pages 支持两种 DNS 配置方式：

方式 1：域名在 Cloudflare 管理（推荐）

Section titled “方式 1：域名在 Cloudflare 管理（推荐）”

如果你的域名 DNS 已托管在 Cloudflare：

  1. Cloudflare Pages 会自动添加 CNAME 记录
  2. 无需手动配置，一键完成

优点：

  • ✅ 自动配置，无需手动操作
  • ✅ 自动 HTTPS 证书
  • ✅ 集成 CDN 加速

方式 2：域名在其他服务商

Section titled “方式 2：域名在其他服务商”

在你的域名服务商处添加 DNS 记录：

子域名（如 blog.example.com）：

类型名称值
CNAMEblogyour-project.pages.dev

根域名（如 example.com）：

类型名称值
CNAME@your-project.pages.dev

或者使用 A 记录（部分 DNS 服务商不支持根域名 CNAME）：

TODO: 添加 DNS 配置示例截图

迁移域名到 Cloudflare（可选）

Section titled “迁移域名到 Cloudflare（可选）”

如果你想享受 Cloudflare 的完整功能（自动 DNS 配置、DDoS 防护等），可以将域名 NS 记录指向 Cloudflare：

  1. 在 Cloudflare Dashboard 添加站点
  2. 按照指引修改域名注册商的 NS 记录
  3. 等待 DNS 生效（通常 24 小时内）

HTTPS 证书

Section titled “HTTPS 证书”

Cloudflare Pages 自动为所有域名提供免费的 SSL 证书。

添加域名后会自动：

  1. 验证域名所有权
  2. 申请并配置 SSL 证书
  3. 启用 HTTPS
  4. 强制 HTTPS 重定向

环境变量

Section titled “环境变量”

管理环境变量

Section titled “管理环境变量”
  1. 进入项目的 Settings → Environment variables
  2. 点击 “Add variables”
  3. 输入变量名和值
  4. 选择环境（Production / Preview）
  5. 点击 “Save”

TODO: 添加环境变量管理界面截图

示例：

变量名Production 值Preview 值
SITE_URLhttps://yourdomain.comhttps://preview.pages.dev
NODE_VERSION2020

在代码中使用

Section titled “在代码中使用”
astro.config.mjs
export default defineConfig({
  site: process.env.SITE_URL || "https://yourdomain.com",
});

性能优化

Section titled “性能优化”

1. 全球 CDN

Section titled “1. 全球 CDN”

Cloudflare 拥有全球最大的 CDN 网络之一，覆盖 300+ 城市。

你的站点会自动分发到离用户最近的 CDN 节点，大幅提升访问速度。

覆盖范围：

  • 🌏 亚洲（香港、东京、新加坡、首尔等）
  • 🌍 欧洲（伦敦、法兰克福、阿姆斯特丹等）
  • 🌎 美洲（纽约、洛杉矶、圣保罗等）
  • 🌍 其他地区全面覆盖

2. 自动缓存优化

Section titled “2. 自动缓存优化”

Cloudflare Pages 自动为静态资源配置缓存策略：

  • HTML 文件：短期缓存，确保内容及时更新
  • 静态资源（CSS、JS、图片）：长期缓存，提升二次访问速度
  • 边缘缓存：内容缓存在全球节点，减少回源请求

3. HTTP/3 支持

Section titled “3. HTTP/3 支持”

Cloudflare Pages 自动启用 HTTP/3（基于 QUIC 协议），提供更快的连接速度和更好的弱网环境表现。

4. Brotli 压缩

Section titled “4. Brotli 压缩”

自动启用 Brotli 压缩算法，相比 Gzip 压缩率提升 15-25%，减少传输数据量。

构建优化

Section titled “构建优化”

构建时间

Section titled “构建时间”

首次部署：约 2-4 分钟
后续部署：约 1-2 分钟（受益于缓存）

加速构建

Section titled “加速构建”

如果构建时间过长，可以尝试：

  1. 启用字体子集化：减少字体文件体积（参考字体配置文档）
  2. 优化图片资源：压缩图片文件
  3. 减少不必要的依赖：检查 package.json
  4. 使用增量构建：Astro 支持增量构建（需要配置）

常见问题

Section titled “常见问题”

Q: 构建失败，提示 “Build failed”？

Section titled “Q: 构建失败，提示 “Build failed”？”

排查步骤：

  1. 查看构建日志，定位具体错误
  2. 检查 package.json 中的 build 脚本是否正确
  3. 确认本地运行 bun run build 成功
  4. 检查环境变量是否配置正确

常见原因：

  • 缺少必要的环境变量
  • 依赖安装失败
  • 构建脚本错误

Q: 搜索功能不可用？

Section titled “Q: 搜索功能不可用？”

原因：构建命令未包含 Pagefind 索引生成。

解决方案：

确认 package.json 中的 build 脚本包含索引生成：

package.json
{
  "scripts": {
    "build": "bun run build:site && bun run build:index"
  }
}

Q: 部署成功但页面样式丢失？

Section titled “Q: 部署成功但页面样式丢失？”

可能原因：

  • 站点 URL 配置错误
  • 静态资源路径问题

解决方案：

  1. 检查 astro.config.mjs 中的 site 配置
  2. 确保使用 HTTPS
  3. 清除浏览器缓存并刷新
  4. 检查浏览器控制台是否有资源加载错误

Q: 如何回滚到之前的版本？

Section titled “Q: 如何回滚到之前的版本？”
  1. 进入项目的 Deployments 标签
  2. 找到之前成功的部署
  3. 点击 “Rollback to this deployment”

或者使用 Git 回滚：

Terminal window
# 回滚到上一个提交
git revert HEAD
git push origin main


# Cloudflare Pages 会自动重新部署

TODO: 添加回滚操作界面截图

Q: 如何修改构建配置？

Section titled “Q: 如何修改构建配置？”
  1. 进入项目的 Settings → Builds & deployments
  2. 编辑 Build configuration
  3. 修改构建命令或输出目录
  4. 点击 “Save”
  5. 触发新的部署以应用更改

Q: 预览部署的 URL 是什么？

Section titled “Q: 预览部署的 URL 是什么？”

格式：

  • 分支部署：<BRANCH>.<PROJECT>.pages.dev
  • PR 部署：<PR_NUMBER>.<PROJECT>.pages.dev

示例：

  • 主分支：my-blog.pages.dev
  • dev 分支：dev.my-blog.pages.dev
  • PR #123：123.my-blog.pages.dev

Q: 如何删除项目？

Section titled “Q: 如何删除项目？”
  1. 进入项目的 Settings → General
  2. 滚动到底部，找到 “Delete project”
  3. 输入项目名称确认删除

Q: Cloudflare Pages vs Vercel vs Netlify？

Section titled “Q: Cloudflare Pages vs Vercel vs Netlify？”

选择 Cloudflare Pages：

  • ✅ 需要最快的全球访问速度（最大 CDN 网络）
  • ✅ 域名已在 Cloudflare 管理
  • ✅ 需要强大的 DDoS 防护
  • ✅ 偏好 Cloudflare 生态系统

选择 Vercel：

  • ✅ 更新频率高（更多构建时间）
  • ✅ 需要 Next.js 等框架的深度集成

选择 Netlify：

  • ✅ 需要表单提交功能
  • ✅ 需要分支部署

对于 ShokaX 主题，三者都适用，可以根据个人偏好和已有服务选择。

故障排查

Section titled “故障排查”

构建日志在哪里查看？

Section titled “构建日志在哪里查看？”
  1. 进入项目 Dashboard
  2. 点击 Deployments 标签
  3. 选择任意部署记录
  4. 查看 Build log 详情

TODO: 添加构建日志界面截图

部署状态一直显示 “Building”

Section titled “部署状态一直显示 “Building””

可能原因：

  • 构建脚本卡死（无限循环）
  • 依赖下载缓慢

解决方案：

  1. 等待 5-10 分钟，Cloudflare Pages 会自动超时
  2. 检查构建日志，定位卡死位置
  3. 优化构建脚本，避免耗时操作

静态资源 404

Section titled “静态资源 404”

原因：输出目录配置错误。

解决方案：

确认 Build output directory 设置为 dist（与 astro.config.mjs 中的 outDir 一致）。

域名配置后无法访问

Section titled “域名配置后无法访问”

排查步骤：

  1. 使用 DNS Checker 检查 DNS 是否生效
  2. 确认 CNAME 记录指向正确（your-project.pages.dev）
  3. 检查 SSL 证书状态（Cloudflare 会自动申请）
  4. 清除浏览器缓存并使用无痕模式测试

相关资源

Section titled “相关资源”
津 ICP 备2022001375 号
津公网安备 12011402001353 号